diff --git a/docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from docs/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to docs/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/docs/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/docs/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/docs/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/docs/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/docs/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/docs/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/docs/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from docs/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to docs/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/docs/client-api/changes/_what-is-changes-api-csharp.mdx b/docs/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from docs/client-api/changes/_what-is-changes-api-csharp.mdx rename to docs/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/docs/client-api/changes/_what-is-changes-api-java.mdx b/docs/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from docs/client-api/changes/_what-is-changes-api-java.mdx rename to docs/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/docs/client-api/changes/_what-is-changes-api-nodejs.mdx b/docs/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from docs/client-api/changes/_what-is-changes-api-nodejs.mdx rename to docs/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/docs/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/docs/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/docs/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/docs/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/docs/client-api/changes/how-to-subscribe-to-document-changes.mdx b/docs/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/docs/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/docs/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/docs/client-api/changes/how-to-subscribe-to-index-changes.mdx b/docs/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/docs/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/docs/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/docs/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/docs/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/docs/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/docs/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/docs/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/docs/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/docs/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/docs/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/docs/client-api/changes/what-is-changes-api.mdx b/docs/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/docs/client-api/changes/what-is-changes-api.mdx +++ b/docs/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/docs/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/docs/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from docs/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to docs/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/docs/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/docs/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from docs/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to docs/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from docs/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to docs/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/docs/client-api/cluster/document-conflicts-in-client-side.mdx b/docs/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/docs/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/docs/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/docs/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/docs/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/docs/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/docs/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx b/docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx similarity index 100% rename from docs/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx rename to docs/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx diff --git a/docs/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/docs/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 1ac1806667..190450e14d 100644 --- a/docs/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/docs/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchNodejs from './_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchNodejs from './content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; diff --git a/docs/client-api/commands/_overview-csharp.mdx b/docs/client-api/commands/content/_overview-csharp.mdx similarity index 100% rename from docs/client-api/commands/_overview-csharp.mdx rename to docs/client-api/commands/content/_overview-csharp.mdx diff --git a/docs/client-api/commands/_overview-java.mdx b/docs/client-api/commands/content/_overview-java.mdx similarity index 100% rename from docs/client-api/commands/_overview-java.mdx rename to docs/client-api/commands/content/_overview-java.mdx diff --git a/docs/client-api/commands/_overview-nodejs.mdx b/docs/client-api/commands/content/_overview-nodejs.mdx similarity index 100% rename from docs/client-api/commands/_overview-nodejs.mdx rename to docs/client-api/commands/content/_overview-nodejs.mdx diff --git a/docs/client-api/commands/documents/_delete-csharp.mdx b/docs/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from docs/client-api/commands/documents/_delete-csharp.mdx rename to docs/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/docs/client-api/commands/documents/_delete-java.mdx b/docs/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from docs/client-api/commands/documents/_delete-java.mdx rename to docs/client-api/commands/documents/content/_delete-java.mdx diff --git a/docs/client-api/commands/documents/_delete-nodejs.mdx b/docs/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from docs/client-api/commands/documents/_delete-nodejs.mdx rename to docs/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/docs/client-api/commands/documents/_delete-php.mdx b/docs/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from docs/client-api/commands/documents/_delete-php.mdx rename to docs/client-api/commands/documents/content/_delete-php.mdx diff --git a/docs/client-api/commands/documents/_delete-python.mdx b/docs/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from docs/client-api/commands/documents/_delete-python.mdx rename to docs/client-api/commands/documents/content/_delete-python.mdx diff --git a/docs/client-api/commands/documents/_get-csharp.mdx b/docs/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from docs/client-api/commands/documents/_get-csharp.mdx rename to docs/client-api/commands/documents/content/_get-csharp.mdx diff --git a/docs/client-api/commands/documents/_get-java.mdx b/docs/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from docs/client-api/commands/documents/_get-java.mdx rename to docs/client-api/commands/documents/content/_get-java.mdx diff --git a/docs/client-api/commands/documents/_get-nodejs.mdx b/docs/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from docs/client-api/commands/documents/_get-nodejs.mdx rename to docs/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/docs/client-api/commands/documents/_get-php.mdx b/docs/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from docs/client-api/commands/documents/_get-php.mdx rename to docs/client-api/commands/documents/content/_get-php.mdx diff --git a/docs/client-api/commands/documents/_get-python.mdx b/docs/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from docs/client-api/commands/documents/_get-python.mdx rename to docs/client-api/commands/documents/content/_get-python.mdx diff --git a/docs/client-api/commands/documents/_put-csharp.mdx b/docs/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from docs/client-api/commands/documents/_put-csharp.mdx rename to docs/client-api/commands/documents/content/_put-csharp.mdx diff --git a/docs/client-api/commands/documents/_put-java.mdx b/docs/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from docs/client-api/commands/documents/_put-java.mdx rename to docs/client-api/commands/documents/content/_put-java.mdx diff --git a/docs/client-api/commands/documents/_put-nodejs.mdx b/docs/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from docs/client-api/commands/documents/_put-nodejs.mdx rename to docs/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/docs/client-api/commands/documents/_put-php.mdx b/docs/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from docs/client-api/commands/documents/_put-php.mdx rename to docs/client-api/commands/documents/content/_put-php.mdx diff --git a/docs/client-api/commands/documents/_put-python.mdx b/docs/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from docs/client-api/commands/documents/_put-python.mdx rename to docs/client-api/commands/documents/content/_put-python.mdx diff --git a/docs/client-api/commands/documents/delete.mdx b/docs/client-api/commands/documents/delete.mdx index 61091b815c..a88bb5f5db 100644 --- a/docs/client-api/commands/documents/delete.mdx +++ b/docs/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/docs/client-api/commands/documents/get.mdx b/docs/client-api/commands/documents/get.mdx index 1e303a3f73..325076a4dc 100644 --- a/docs/client-api/commands/documents/get.mdx +++ b/docs/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/docs/client-api/commands/documents/put.mdx b/docs/client-api/commands/documents/put.mdx index ee9e70143c..9c8ba28480 100644 --- a/docs/client-api/commands/documents/put.mdx +++ b/docs/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/docs/client-api/commands/overview.mdx b/docs/client-api/commands/overview.mdx index dd0aca1a6c..744fb40071 100644 --- a/docs/client-api/commands/overview.mdx +++ b/docs/client-api/commands/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/client-api/configuration/_conventions-csharp.mdx b/docs/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from docs/client-api/configuration/_conventions-csharp.mdx rename to docs/client-api/configuration/content/_conventions-csharp.mdx diff --git a/docs/client-api/configuration/_conventions-nodejs.mdx b/docs/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from docs/client-api/configuration/_conventions-nodejs.mdx rename to docs/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/docs/client-api/configuration/_deserialization-csharp.mdx b/docs/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from docs/client-api/configuration/_deserialization-csharp.mdx rename to docs/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/docs/client-api/configuration/_deserialization-java.mdx b/docs/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from docs/client-api/configuration/_deserialization-java.mdx rename to docs/client-api/configuration/content/_deserialization-java.mdx diff --git a/docs/client-api/configuration/_serialization-csharp.mdx b/docs/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from docs/client-api/configuration/_serialization-csharp.mdx rename to docs/client-api/configuration/content/_serialization-csharp.mdx diff --git a/docs/client-api/configuration/_serialization-java.mdx b/docs/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from docs/client-api/configuration/_serialization-java.mdx rename to docs/client-api/configuration/content/_serialization-java.mdx diff --git a/docs/client-api/configuration/conventions.mdx b/docs/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/docs/client-api/configuration/conventions.mdx +++ b/docs/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/docs/client-api/configuration/deserialization.mdx b/docs/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/docs/client-api/configuration/deserialization.mdx +++ b/docs/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/docs/client-api/configuration/identifier-generation/_global-csharp.mdx b/docs/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_global-csharp.mdx rename to docs/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/docs/client-api/configuration/identifier-generation/_global-java.mdx b/docs/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_global-java.mdx rename to docs/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/docs/client-api/configuration/identifier-generation/_global-nodejs.mdx b/docs/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to docs/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/docs/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/docs/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to docs/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/docs/client-api/configuration/identifier-generation/_type-specific-java.mdx b/docs/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to docs/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/docs/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/docs/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from docs/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to docs/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/docs/client-api/configuration/identifier-generation/global.mdx b/docs/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/docs/client-api/configuration/identifier-generation/global.mdx +++ b/docs/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/docs/client-api/configuration/identifier-generation/type-specific.mdx b/docs/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/docs/client-api/configuration/identifier-generation/type-specific.mdx +++ b/docs/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/docs/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/docs/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to docs/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/docs/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/docs/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to docs/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/docs/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/docs/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to docs/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/docs/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/docs/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to docs/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/docs/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/docs/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to docs/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/docs/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/docs/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to docs/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/docs/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/docs/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to docs/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/docs/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/docs/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from docs/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to docs/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/docs/client-api/configuration/load-balance/load-balance-behavior.mdx b/docs/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/docs/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/docs/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/docs/client-api/configuration/load-balance/read-balance-behavior.mdx b/docs/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/docs/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/docs/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/docs/client-api/configuration/serialization.mdx b/docs/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/docs/client-api/configuration/serialization.mdx +++ b/docs/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/docs/client-api/_creating-document-store-csharp.mdx b/docs/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from docs/client-api/_creating-document-store-csharp.mdx rename to docs/client-api/content/_creating-document-store-csharp.mdx diff --git a/docs/client-api/_creating-document-store-java.mdx b/docs/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from docs/client-api/_creating-document-store-java.mdx rename to docs/client-api/content/_creating-document-store-java.mdx diff --git a/docs/client-api/_creating-document-store-nodejs.mdx b/docs/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from docs/client-api/_creating-document-store-nodejs.mdx rename to docs/client-api/content/_creating-document-store-nodejs.mdx diff --git a/docs/client-api/_net-client-versions-csharp.mdx b/docs/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from docs/client-api/_net-client-versions-csharp.mdx rename to docs/client-api/content/_net-client-versions-csharp.mdx diff --git a/docs/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/docs/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from docs/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to docs/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/docs/client-api/_setting-up-authentication-and-authorization-java.mdx b/docs/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from docs/client-api/_setting-up-authentication-and-authorization-java.mdx rename to docs/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/docs/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/docs/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from docs/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to docs/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/docs/client-api/_setting-up-default-database-csharp.mdx b/docs/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from docs/client-api/_setting-up-default-database-csharp.mdx rename to docs/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/docs/client-api/_setting-up-default-database-java.mdx b/docs/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from docs/client-api/_setting-up-default-database-java.mdx rename to docs/client-api/content/_setting-up-default-database-java.mdx diff --git a/docs/client-api/_setting-up-default-database-nodejs.mdx b/docs/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from docs/client-api/_setting-up-default-database-nodejs.mdx rename to docs/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/docs/client-api/_what-is-a-document-store-csharp.mdx b/docs/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from docs/client-api/_what-is-a-document-store-csharp.mdx rename to docs/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/docs/client-api/_what-is-a-document-store-java.mdx b/docs/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from docs/client-api/_what-is-a-document-store-java.mdx rename to docs/client-api/content/_what-is-a-document-store-java.mdx diff --git a/docs/client-api/_what-is-a-document-store-nodejs.mdx b/docs/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from docs/client-api/_what-is-a-document-store-nodejs.mdx rename to docs/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/docs/client-api/creating-document-store.mdx b/docs/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/docs/client-api/creating-document-store.mdx +++ b/docs/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/docs/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index cd09e4587d..0000000000 --- a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/docs/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index c2d1857b87..0000000000 --- a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,134 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/docs/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 12e6eedbd2..0000000000 --- a/docs/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to docs/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/docs/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/docs/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/docs/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/docs/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/docs/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/docs/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/concurrent-subscriptions.mdx b/docs/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/docs/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/docs/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/consumption/api-overview.mdx b/docs/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/docs/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/docs/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/docs/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to docs/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/docs/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to docs/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/docs/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to docs/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/docs/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to docs/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/docs/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to docs/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_examples-java.mdx b/docs/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_examples-java.mdx rename to docs/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/docs/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to docs/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_examples-python.mdx b/docs/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_examples-python.mdx rename to docs/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to docs/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/docs/client-api/data-subscriptions/consumption/examples.mdx b/docs/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/docs/client-api/data-subscriptions/consumption/examples.mdx +++ b/docs/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/docs/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/docs/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/docs/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/docs/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to docs/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/docs/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/docs/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to docs/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..30fd3f7254 --- /dev/null +++ b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..aaa26a16f7 --- /dev/null +++ b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,134 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..d82e45f68c --- /dev/null +++ b/docs/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/docs/client-api/data-subscriptions/creation/api-overview.mdx b/docs/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/docs/client-api/data-subscriptions/creation/api-overview.mdx +++ b/docs/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/docs/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to docs/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/docs/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/docs/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to docs/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/creation/_api-overview-python.mdx b/docs/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to docs/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/docs/client-api/data-subscriptions/creation/_examples-csharp.mdx b/docs/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to docs/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/docs/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/docs/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to docs/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/creation/_examples-python.mdx b/docs/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_examples-python.mdx rename to docs/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from docs/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to docs/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/docs/client-api/data-subscriptions/creation/examples.mdx b/docs/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/docs/client-api/data-subscriptions/creation/examples.mdx +++ b/docs/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/docs/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/docs/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/docs/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/docs/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/docs/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 881ea78195..16791e745a 100644 --- a/docs/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/docs/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/docs/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/docs/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from docs/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to docs/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/docs/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/docs/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from docs/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to docs/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/docs/client-api/document-identifiers/hilo-algorithm.mdx b/docs/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/docs/client-api/document-identifiers/hilo-algorithm.mdx +++ b/docs/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/docs/client-api/document-identifiers/working-with-document-identifiers.mdx b/docs/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/docs/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/docs/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/docs/client-api/how-to/_handle-document-relationships-csharp.mdx b/docs/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from docs/client-api/how-to/_handle-document-relationships-csharp.mdx rename to docs/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/docs/client-api/how-to/_handle-document-relationships-java.mdx b/docs/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from docs/client-api/how-to/_handle-document-relationships-java.mdx rename to docs/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/docs/client-api/how-to/_handle-document-relationships-nodejs.mdx b/docs/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from docs/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to docs/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/docs/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/docs/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from docs/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to docs/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/docs/client-api/how-to/_setup-aggressive-caching-java.mdx b/docs/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from docs/client-api/how-to/_setup-aggressive-caching-java.mdx rename to docs/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/docs/client-api/how-to/handle-document-relationships.mdx b/docs/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/docs/client-api/how-to/handle-document-relationships.mdx +++ b/docs/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/docs/client-api/how-to/setup-aggressive-caching.mdx b/docs/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/docs/client-api/how-to/setup-aggressive-caching.mdx +++ b/docs/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/docs/client-api/net-client-versions.mdx b/docs/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/docs/client-api/net-client-versions.mdx +++ b/docs/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/docs/client-api/operations/common/_delete-by-query-csharp.mdx b/docs/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from docs/client-api/operations/common/_delete-by-query-csharp.mdx rename to docs/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/docs/client-api/operations/common/_delete-by-query-java.mdx b/docs/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from docs/client-api/operations/common/_delete-by-query-java.mdx rename to docs/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/docs/client-api/operations/common/_delete-by-query-nodejs.mdx b/docs/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from docs/client-api/operations/common/_delete-by-query-nodejs.mdx rename to docs/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/docs/client-api/operations/common/_delete-by-query-php.mdx b/docs/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from docs/client-api/operations/common/_delete-by-query-php.mdx rename to docs/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/docs/client-api/operations/common/_delete-by-query-python.mdx b/docs/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from docs/client-api/operations/common/_delete-by-query-python.mdx rename to docs/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/docs/client-api/operations/common/delete-by-query.mdx b/docs/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/docs/client-api/operations/common/delete-by-query.mdx +++ b/docs/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/docs/client-api/operations/_what-are-operations-csharp.mdx b/docs/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from docs/client-api/operations/_what-are-operations-csharp.mdx rename to docs/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/docs/client-api/operations/_what-are-operations-java.mdx b/docs/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from docs/client-api/operations/_what-are-operations-java.mdx rename to docs/client-api/operations/content/_what-are-operations-java.mdx diff --git a/docs/client-api/operations/_what-are-operations-nodejs.mdx b/docs/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from docs/client-api/operations/_what-are-operations-nodejs.mdx rename to docs/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/docs/client-api/operations/_what-are-operations-php.mdx b/docs/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from docs/client-api/operations/_what-are-operations-php.mdx rename to docs/client-api/operations/content/_what-are-operations-php.mdx diff --git a/docs/client-api/operations/_what-are-operations-python.mdx b/docs/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from docs/client-api/operations/_what-are-operations-python.mdx rename to docs/client-api/operations/content/_what-are-operations-python.mdx diff --git a/docs/client-api/operations/counters/_counter-batch-csharp.mdx b/docs/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from docs/client-api/operations/counters/_counter-batch-csharp.mdx rename to docs/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/docs/client-api/operations/counters/_counter-batch-java.mdx b/docs/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from docs/client-api/operations/counters/_counter-batch-java.mdx rename to docs/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/docs/client-api/operations/counters/_counter-batch-nodejs.mdx b/docs/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from docs/client-api/operations/counters/_counter-batch-nodejs.mdx rename to docs/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/docs/client-api/operations/counters/_counter-batch-php.mdx b/docs/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from docs/client-api/operations/counters/_counter-batch-php.mdx rename to docs/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/docs/client-api/operations/counters/_get-counters-csharp.mdx b/docs/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from docs/client-api/operations/counters/_get-counters-csharp.mdx rename to docs/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/docs/client-api/operations/counters/_get-counters-java.mdx b/docs/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from docs/client-api/operations/counters/_get-counters-java.mdx rename to docs/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/docs/client-api/operations/counters/_get-counters-nodejs.mdx b/docs/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from docs/client-api/operations/counters/_get-counters-nodejs.mdx rename to docs/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/docs/client-api/operations/counters/_get-counters-php.mdx b/docs/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from docs/client-api/operations/counters/_get-counters-php.mdx rename to docs/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/docs/client-api/operations/counters/counter-batch.mdx b/docs/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/docs/client-api/operations/counters/counter-batch.mdx +++ b/docs/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/docs/client-api/operations/counters/get-counters.mdx b/docs/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/docs/client-api/operations/counters/get-counters.mdx +++ b/docs/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/docs/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from docs/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to docs/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/docs/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/docs/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/docs/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/docs/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/docs/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/docs/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/docs/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/docs/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to docs/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to docs/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to docs/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/docs/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/docs/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/docs/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/docs/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/docs/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/docs/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/docs/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/docs/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/docs/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/docs/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/docs/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index 411e7a0097..0de1650d28 100644 --- a/docs/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/docs/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/docs/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/docs/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to docs/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/docs/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/docs/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to docs/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/docs/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/docs/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to docs/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/docs/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/docs/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 0c2b4eac5d..375985d7be 100644 --- a/docs/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/docs/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/docs/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/docs/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 097f3eefc1..170c2de116 100644 --- a/docs/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/docs/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/docs/client-api/operations/maintenance/_get-stats-csharp.mdx b/docs/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/_get-stats-csharp.mdx rename to docs/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/docs/client-api/operations/maintenance/_get-stats-java.mdx b/docs/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/_get-stats-java.mdx rename to docs/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/docs/client-api/operations/maintenance/_get-stats-nodejs.mdx b/docs/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to docs/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/_get-stats-php.mdx b/docs/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/_get-stats-php.mdx rename to docs/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/docs/client-api/operations/maintenance/_get-stats-python.mdx b/docs/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/_get-stats-python.mdx rename to docs/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/docs/client-api/operations/maintenance/etl/add-etl.mdx b/docs/client-api/operations/maintenance/etl/add-etl.mdx index e1ee997ddf..f4df4215da 100644 --- a/docs/client-api/operations/maintenance/etl/add-etl.mdx +++ b/docs/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/docs/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to docs/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/docs/client-api/operations/maintenance/etl/_add-etl-java.mdx b/docs/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to docs/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/docs/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/docs/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to docs/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/docs/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to docs/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/docs/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/docs/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to docs/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/docs/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/docs/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to docs/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/docs/client-api/operations/maintenance/etl/_update-etl-java.mdx b/docs/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to docs/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/docs/client-api/operations/maintenance/etl/reset-etl.mdx b/docs/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/docs/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/docs/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/docs/client-api/operations/maintenance/etl/update-etl.mdx b/docs/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/docs/client-api/operations/maintenance/etl/update-etl.mdx +++ b/docs/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/docs/client-api/operations/maintenance/get-stats.mdx b/docs/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/docs/client-api/operations/maintenance/get-stats.mdx +++ b/docs/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/docs/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to docs/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-java.mdx b/docs/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to docs/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/docs/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to docs/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-php.mdx b/docs/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to docs/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-python.mdx b/docs/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to docs/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/docs/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/docs/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to docs/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/docs/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/docs/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to docs/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/docs/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to docs/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/docs/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/docs/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to docs/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/docs/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/docs/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to docs/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/docs/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/docs/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to docs/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/docs/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to docs/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/docs/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/docs/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to docs/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/docs/client-api/operations/maintenance/identities/get-identities.mdx b/docs/client-api/operations/maintenance/identities/get-identities.mdx index c7bbd9c2d5..0088f23bbf 100644 --- a/docs/client-api/operations/maintenance/identities/get-identities.mdx +++ b/docs/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/identities/increment-next-identity.mdx b/docs/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/docs/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/docs/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/identities/seed-identity.mdx b/docs/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/docs/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/docs/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/docs/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/docs/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from docs/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to docs/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/docs/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/docs/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/docs/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/docs/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/delete-index.mdx b/docs/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/docs/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/disable-index.mdx b/docs/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/docs/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/enable-index.mdx b/docs/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/docs/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/get-index-errors.mdx b/docs/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/docs/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/docs/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/get-index-names.mdx b/docs/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/docs/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/docs/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/get-index.mdx b/docs/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/docs/client-api/operations/maintenance/indexes/get-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/get-indexes.mdx b/docs/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/docs/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/docs/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/get-terms.mdx b/docs/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/docs/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/docs/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/index-has-changed.mdx b/docs/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/docs/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/docs/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/put-indexes.mdx b/docs/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/docs/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/docs/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/reset-index.mdx b/docs/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/docs/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/set-index-lock.mdx b/docs/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/docs/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/docs/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/set-index-priority.mdx b/docs/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/docs/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/docs/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/start-index.mdx b/docs/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/docs/client-api/operations/maintenance/indexes/start-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/start-indexing.mdx b/docs/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/docs/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/docs/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/stop-index.mdx b/docs/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/docs/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/docs/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/indexes/stop-indexing.mdx b/docs/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/docs/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/docs/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/docs/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx b/docs/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx rename to docs/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx diff --git a/docs/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx b/docs/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx index ecbdd10352..619c94b24d 100644 --- a/docs/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx +++ b/docs/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OngoingTaskOperationsCsharp from './_ongoing-task-operations-csharp.mdx'; +import OngoingTaskOperationsCsharp from './content/_ongoing-task-operations-csharp.mdx'; diff --git a/docs/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/docs/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from docs/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to docs/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/docs/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/docs/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from docs/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to docs/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/docs/client-api/operations/maintenance/sorters/put-sorter.mdx b/docs/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/docs/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/docs/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/docs/client-api/operations/patching/_set-based-csharp.mdx b/docs/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from docs/client-api/operations/patching/_set-based-csharp.mdx rename to docs/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/docs/client-api/operations/patching/_set-based-java.mdx b/docs/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from docs/client-api/operations/patching/_set-based-java.mdx rename to docs/client-api/operations/patching/content/_set-based-java.mdx diff --git a/docs/client-api/operations/patching/_set-based-nodejs.mdx b/docs/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from docs/client-api/operations/patching/_set-based-nodejs.mdx rename to docs/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/docs/client-api/operations/patching/_single-document-csharp.mdx b/docs/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from docs/client-api/operations/patching/_single-document-csharp.mdx rename to docs/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/docs/client-api/operations/patching/_single-document-java.mdx b/docs/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from docs/client-api/operations/patching/_single-document-java.mdx rename to docs/client-api/operations/patching/content/_single-document-java.mdx diff --git a/docs/client-api/operations/patching/_single-document-nodejs.mdx b/docs/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from docs/client-api/operations/patching/_single-document-nodejs.mdx rename to docs/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/docs/client-api/operations/patching/set-based.mdx b/docs/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/docs/client-api/operations/patching/set-based.mdx +++ b/docs/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/docs/client-api/operations/patching/single-document.mdx b/docs/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/docs/client-api/operations/patching/single-document.mdx +++ b/docs/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/add-database-node.mdx b/docs/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/docs/client-api/operations/server-wide/add-database-node.mdx +++ b/docs/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to docs/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/docs/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to docs/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/docs/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to docs/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/docs/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to docs/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/docs/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to docs/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/docs/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to docs/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/docs/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to docs/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/docs/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to docs/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/docs/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to docs/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/docs/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/docs/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/docs/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/certificates/delete-certificate.mdx b/docs/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/docs/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/docs/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/certificates/get-certificate.mdx b/docs/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/docs/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/docs/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/docs/client-api/operations/server-wide/certificates/get-certificates.mdx b/docs/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/docs/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/docs/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/docs/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/docs/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/docs/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/docs/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/compact-database.mdx b/docs/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/docs/client-api/operations/server-wide/compact-database.mdx +++ b/docs/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/docs/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to docs/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/docs/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/docs/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to docs/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/docs/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to docs/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/docs/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/docs/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to docs/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/docs/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/docs/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/docs/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/docs/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/docs/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/docs/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/_add-database-node-csharp.mdx b/docs/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to docs/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/docs/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to docs/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/_add-database-node-php.mdx b/docs/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_add-database-node-php.mdx rename to docs/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/docs/client-api/operations/server-wide/_add-database-node-python.mdx b/docs/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_add-database-node-python.mdx rename to docs/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/docs/client-api/operations/server-wide/_compact-database-csharp.mdx b/docs/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_compact-database-csharp.mdx rename to docs/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_compact-database-nodejs.mdx b/docs/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to docs/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/_compact-database-php.mdx b/docs/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_compact-database-php.mdx rename to docs/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/docs/client-api/operations/server-wide/_compact-database-python.mdx b/docs/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_compact-database-python.mdx rename to docs/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/docs/client-api/operations/server-wide/_create-database-csharp.mdx b/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_create-database-csharp.mdx rename to docs/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_create-database-java.mdx b/docs/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_create-database-java.mdx rename to docs/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/docs/client-api/operations/server-wide/_delete-database-csharp.mdx b/docs/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_delete-database-csharp.mdx rename to docs/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_delete-database-java.mdx b/docs/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_delete-database-java.mdx rename to docs/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/docs/client-api/operations/server-wide/_get-build-number-csharp.mdx b/docs/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to docs/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_get-database-names-csharp.mdx b/docs/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to docs/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_get-database-names-java.mdx b/docs/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_get-database-names-java.mdx rename to docs/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/docs/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/docs/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to docs/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/docs/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to docs/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/docs/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to docs/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_restore-backup-csharp.mdx b/docs/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to docs/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_restore-backup-java.mdx b/docs/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_restore-backup-java.mdx rename to docs/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/docs/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/docs/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to docs/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/docs/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to docs/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/docs/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/docs/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to docs/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/docs/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to docs/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/docs/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/docs/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to docs/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/docs/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/docs/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to docs/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/docs/client-api/operations/server-wide/create-database.mdx b/docs/client-api/operations/server-wide/create-database.mdx index 06626431e0..59effdb582 100644 --- a/docs/client-api/operations/server-wide/create-database.mdx +++ b/docs/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/docs/client-api/operations/server-wide/delete-database.mdx b/docs/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/docs/client-api/operations/server-wide/delete-database.mdx +++ b/docs/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/docs/client-api/operations/server-wide/get-build-number.mdx b/docs/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/docs/client-api/operations/server-wide/get-build-number.mdx +++ b/docs/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/get-database-names.mdx b/docs/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/docs/client-api/operations/server-wide/get-database-names.mdx +++ b/docs/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/docs/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/docs/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to docs/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/docs/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/docs/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to docs/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/docs/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/docs/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 717fff9f05..0a89243169 100644 --- a/docs/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/docs/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/docs/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 40fd888f09..3cdddcb768 100644 --- a/docs/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/docs/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/modify-conflict-solver.mdx b/docs/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/docs/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/docs/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/promote-database-node.mdx b/docs/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/docs/client-api/operations/server-wide/promote-database-node.mdx +++ b/docs/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/reorder-database-members.mdx b/docs/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/docs/client-api/operations/server-wide/reorder-database-members.mdx +++ b/docs/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/docs/client-api/operations/server-wide/restore-backup.mdx b/docs/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/docs/client-api/operations/server-wide/restore-backup.mdx +++ b/docs/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/docs/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from docs/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to docs/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/docs/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/docs/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from docs/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to docs/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/docs/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/docs/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/docs/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/docs/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/toggle-databases-state.mdx b/docs/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/docs/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/docs/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/docs/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/docs/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/docs/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/docs/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/docs/client-api/operations/what-are-operations.mdx b/docs/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/docs/client-api/operations/what-are-operations.mdx +++ b/docs/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/docs/client-api/security/_deserialization-security-csharp.mdx b/docs/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from docs/client-api/security/_deserialization-security-csharp.mdx rename to docs/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/docs/client-api/security/deserialization-security.mdx b/docs/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/docs/client-api/security/deserialization-security.mdx +++ b/docs/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/docs/client-api/session/cluster-transaction/_overview-csharp.mdx b/docs/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from docs/client-api/session/cluster-transaction/_overview-csharp.mdx rename to docs/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/docs/client-api/session/cluster-transaction/_overview-nodejs.mdx b/docs/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from docs/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to docs/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/docs/client-api/session/cluster-transaction/_overview-php.mdx b/docs/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from docs/client-api/session/cluster-transaction/_overview-php.mdx rename to docs/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/docs/client-api/session/cluster-transaction/_overview-python.mdx b/docs/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from docs/client-api/session/cluster-transaction/_overview-python.mdx rename to docs/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/docs/client-api/session/cluster-transaction/overview.mdx b/docs/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/docs/client-api/session/cluster-transaction/overview.mdx +++ b/docs/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to docs/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to docs/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-caching-java.mdx b/docs/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-caching-php.mdx b/docs/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/docs/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/docs/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to docs/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from docs/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to docs/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/docs/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/docs/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/docs/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/docs/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/docs/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/docs/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/docs/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/docs/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/docs/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/docs/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/how-to-disable-caching.mdx b/docs/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/docs/client-api/session/configuration/how-to-disable-caching.mdx +++ b/docs/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/how-to-disable-tracking.mdx b/docs/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/docs/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/docs/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/docs/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/docs/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/docs/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/docs/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/docs/client-api/session/_deleting-entities-csharp.mdx b/docs/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/_deleting-entities-csharp.mdx rename to docs/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/docs/client-api/session/_deleting-entities-java.mdx b/docs/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from docs/client-api/session/_deleting-entities-java.mdx rename to docs/client-api/session/content/_deleting-entities-java.mdx diff --git a/docs/client-api/session/_deleting-entities-nodejs.mdx b/docs/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/_deleting-entities-nodejs.mdx rename to docs/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/docs/client-api/session/_deleting-entities-php.mdx b/docs/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from docs/client-api/session/_deleting-entities-php.mdx rename to docs/client-api/session/content/_deleting-entities-php.mdx diff --git a/docs/client-api/session/_deleting-entities-python.mdx b/docs/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from docs/client-api/session/_deleting-entities-python.mdx rename to docs/client-api/session/content/_deleting-entities-python.mdx diff --git a/docs/client-api/session/_loading-entities-csharp.mdx b/docs/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/_loading-entities-csharp.mdx rename to docs/client-api/session/content/_loading-entities-csharp.mdx diff --git a/docs/client-api/session/_loading-entities-java.mdx b/docs/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from docs/client-api/session/_loading-entities-java.mdx rename to docs/client-api/session/content/_loading-entities-java.mdx diff --git a/docs/client-api/session/_loading-entities-nodejs.mdx b/docs/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/_loading-entities-nodejs.mdx rename to docs/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/docs/client-api/session/_loading-entities-php.mdx b/docs/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from docs/client-api/session/_loading-entities-php.mdx rename to docs/client-api/session/content/_loading-entities-php.mdx diff --git a/docs/client-api/session/_loading-entities-python.mdx b/docs/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from docs/client-api/session/_loading-entities-python.mdx rename to docs/client-api/session/content/_loading-entities-python.mdx diff --git a/docs/client-api/session/_opening-a-session-csharp.mdx b/docs/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from docs/client-api/session/_opening-a-session-csharp.mdx rename to docs/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/docs/client-api/session/_opening-a-session-java.mdx b/docs/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from docs/client-api/session/_opening-a-session-java.mdx rename to docs/client-api/session/content/_opening-a-session-java.mdx diff --git a/docs/client-api/session/_opening-a-session-nodejs.mdx b/docs/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from docs/client-api/session/_opening-a-session-nodejs.mdx rename to docs/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/docs/client-api/session/_opening-a-session-php.mdx b/docs/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from docs/client-api/session/_opening-a-session-php.mdx rename to docs/client-api/session/content/_opening-a-session-php.mdx diff --git a/docs/client-api/session/_opening-a-session-python.mdx b/docs/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from docs/client-api/session/_opening-a-session-python.mdx rename to docs/client-api/session/content/_opening-a-session-python.mdx diff --git a/docs/client-api/session/_saving-changes-csharp.mdx b/docs/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from docs/client-api/session/_saving-changes-csharp.mdx rename to docs/client-api/session/content/_saving-changes-csharp.mdx diff --git a/docs/client-api/session/_saving-changes-java.mdx b/docs/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from docs/client-api/session/_saving-changes-java.mdx rename to docs/client-api/session/content/_saving-changes-java.mdx diff --git a/docs/client-api/session/_saving-changes-nodejs.mdx b/docs/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from docs/client-api/session/_saving-changes-nodejs.mdx rename to docs/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/docs/client-api/session/_saving-changes-php.mdx b/docs/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from docs/client-api/session/_saving-changes-php.mdx rename to docs/client-api/session/content/_saving-changes-php.mdx diff --git a/docs/client-api/session/_saving-changes-python.mdx b/docs/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from docs/client-api/session/_saving-changes-python.mdx rename to docs/client-api/session/content/_saving-changes-python.mdx diff --git a/docs/client-api/session/_storing-entities-csharp.mdx b/docs/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/_storing-entities-csharp.mdx rename to docs/client-api/session/content/_storing-entities-csharp.mdx diff --git a/docs/client-api/session/_storing-entities-java.mdx b/docs/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from docs/client-api/session/_storing-entities-java.mdx rename to docs/client-api/session/content/_storing-entities-java.mdx diff --git a/docs/client-api/session/_storing-entities-nodejs.mdx b/docs/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/_storing-entities-nodejs.mdx rename to docs/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/docs/client-api/session/_storing-entities-php.mdx b/docs/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from docs/client-api/session/_storing-entities-php.mdx rename to docs/client-api/session/content/_storing-entities-php.mdx diff --git a/docs/client-api/session/_storing-entities-python.mdx b/docs/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from docs/client-api/session/_storing-entities-python.mdx rename to docs/client-api/session/content/_storing-entities-python.mdx diff --git a/docs/client-api/session/_updating-entities-csharp.mdx b/docs/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/_updating-entities-csharp.mdx rename to docs/client-api/session/content/_updating-entities-csharp.mdx diff --git a/docs/client-api/session/_updating-entities-nodejs.mdx b/docs/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/_updating-entities-nodejs.mdx rename to docs/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/docs/client-api/session/_updating-entities-php.mdx b/docs/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from docs/client-api/session/_updating-entities-php.mdx rename to docs/client-api/session/content/_updating-entities-php.mdx diff --git a/docs/client-api/session/_updating-entities-python.mdx b/docs/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from docs/client-api/session/_updating-entities-python.mdx rename to docs/client-api/session/content/_updating-entities-python.mdx diff --git a/docs/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from docs/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/docs/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from docs/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/docs/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from docs/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/docs/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from docs/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/docs/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from docs/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to docs/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/docs/client-api/session/deleting-entities.mdx b/docs/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/docs/client-api/session/deleting-entities.mdx +++ b/docs/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/check-if-attachment-exists.mdx b/docs/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/docs/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/docs/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/check-if-document-exists.mdx b/docs/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/docs/client-api/session/how-to/check-if-document-exists.mdx +++ b/docs/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/check-if-entity-has-changed.mdx b/docs/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/docs/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/docs/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/docs/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/docs/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/docs/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/clear-a-session.mdx b/docs/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/docs/client-api/session/how-to/clear-a-session.mdx +++ b/docs/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/docs/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to docs/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/docs/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/docs/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to docs/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/docs/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/docs/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to docs/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/docs/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/docs/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to docs/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/docs/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/docs/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to docs/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/docs/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/docs/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to docs/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/docs/client-api/session/how-to/_check-if-document-exists-java.mdx b/docs/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-document-exists-java.mdx rename to docs/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/docs/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/docs/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to docs/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/docs/client-api/session/how-to/_check-if-document-exists-php.mdx b/docs/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-document-exists-php.mdx rename to docs/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/docs/client-api/session/how-to/_check-if-document-exists-python.mdx b/docs/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-document-exists-python.mdx rename to docs/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/docs/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/docs/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to docs/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/docs/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/docs/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to docs/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/docs/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/docs/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to docs/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/docs/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/docs/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to docs/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/docs/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/docs/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to docs/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to docs/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/docs/client-api/session/how-to/_clear-a-session-csharp.mdx b/docs/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_clear-a-session-csharp.mdx rename to docs/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/docs/client-api/session/how-to/_clear-a-session-java.mdx b/docs/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_clear-a-session-java.mdx rename to docs/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/docs/client-api/session/how-to/_clear-a-session-nodejs.mdx b/docs/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to docs/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/docs/client-api/session/how-to/_clear-a-session-php.mdx b/docs/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_clear-a-session-php.mdx rename to docs/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/docs/client-api/session/how-to/_clear-a-session-python.mdx b/docs/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_clear-a-session-python.mdx rename to docs/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/docs/client-api/session/how-to/_defer-operations-csharp.mdx b/docs/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_defer-operations-csharp.mdx rename to docs/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/docs/client-api/session/how-to/_defer-operations-java.mdx b/docs/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_defer-operations-java.mdx rename to docs/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/docs/client-api/session/how-to/_defer-operations-nodejs.mdx b/docs/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_defer-operations-nodejs.mdx rename to docs/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/docs/client-api/session/how-to/_defer-operations-php.mdx b/docs/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_defer-operations-php.mdx rename to docs/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/docs/client-api/session/how-to/_defer-operations-python.mdx b/docs/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_defer-operations-python.mdx rename to docs/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/docs/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/docs/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to docs/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/docs/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/docs/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to docs/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/docs/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/docs/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to docs/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/docs/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/docs/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to docs/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/docs/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/docs/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to docs/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/docs/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/docs/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-current-session-node-csharp.mdx b/docs/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to docs/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-current-session-node-java.mdx b/docs/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-current-session-node-java.mdx rename to docs/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/docs/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/docs/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-current-session-node-php.mdx b/docs/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-current-session-node-php.mdx rename to docs/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/docs/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/docs/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to docs/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-entity-change-vector-java.mdx b/docs/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to docs/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/docs/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/docs/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-entity-change-vector-php.mdx b/docs/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to docs/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/docs/client-api/session/how-to/_get-entity-change-vector-python.mdx b/docs/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to docs/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/docs/client-api/session/how-to/_get-entity-counters-csharp.mdx b/docs/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to docs/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/docs/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-entity-counters-php.mdx b/docs/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-counters-php.mdx rename to docs/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/docs/client-api/session/how-to/_get-entity-counters-python.mdx b/docs/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-counters-python.mdx rename to docs/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/docs/client-api/session/how-to/_get-entity-id-csharp.mdx b/docs/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-id-csharp.mdx rename to docs/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-entity-id-java.mdx b/docs/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-id-java.mdx rename to docs/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/docs/client-api/session/how-to/_get-entity-id-nodejs.mdx b/docs/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/docs/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to docs/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-entity-last-modified-java.mdx b/docs/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to docs/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/docs/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/docs/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/docs/client-api/session/how-to/_get-entity-last-modified-php.mdx b/docs/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to docs/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/docs/client-api/session/how-to/_get-entity-last-modified-python.mdx b/docs/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to docs/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/docs/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/docs/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to docs/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/docs/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/docs/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to docs/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/docs/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/docs/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to docs/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/docs/client-api/session/how-to/_ignore-entity-changes-java.mdx b/docs/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to docs/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/docs/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/docs/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to docs/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/docs/client-api/session/how-to/_ignore-entity-changes-php.mdx b/docs/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to docs/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/docs/client-api/session/how-to/_ignore-entity-changes-python.mdx b/docs/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to docs/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/docs/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/docs/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to docs/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/docs/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/docs/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to docs/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/docs/client-api/session/how-to/_perform-operations-lazily-php.mdx b/docs/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to docs/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/docs/client-api/session/how-to/_perform-operations-lazily-python.mdx b/docs/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to docs/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/docs/client-api/session/how-to/_refresh-entity-csharp.mdx b/docs/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_refresh-entity-csharp.mdx rename to docs/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/docs/client-api/session/how-to/_refresh-entity-java.mdx b/docs/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_refresh-entity-java.mdx rename to docs/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/docs/client-api/session/how-to/_refresh-entity-nodejs.mdx b/docs/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to docs/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/docs/client-api/session/how-to/_refresh-entity-php.mdx b/docs/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from docs/client-api/session/how-to/_refresh-entity-php.mdx rename to docs/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/docs/client-api/session/how-to/_refresh-entity-python.mdx b/docs/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from docs/client-api/session/how-to/_refresh-entity-python.mdx rename to docs/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/docs/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/docs/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from docs/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to docs/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/docs/client-api/session/how-to/_subscribe-to-events-java.mdx b/docs/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from docs/client-api/session/how-to/_subscribe-to-events-java.mdx rename to docs/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/docs/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/docs/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from docs/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to docs/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/docs/client-api/session/how-to/defer-operations.mdx b/docs/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/docs/client-api/session/how-to/defer-operations.mdx +++ b/docs/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/evict-entity-from-a-session.mdx b/docs/client-api/session/how-to/evict-entity-from-a-session.mdx index 38cfde8172..fd92eb84e0 100644 --- a/docs/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/docs/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/docs/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/docs/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/docs/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-current-session-node.mdx b/docs/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/docs/client-api/session/how-to/get-current-session-node.mdx +++ b/docs/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-entity-change-vector.mdx b/docs/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/docs/client-api/session/how-to/get-entity-change-vector.mdx +++ b/docs/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-entity-counters.mdx b/docs/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/docs/client-api/session/how-to/get-entity-counters.mdx +++ b/docs/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-entity-id.mdx b/docs/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/docs/client-api/session/how-to/get-entity-id.mdx +++ b/docs/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-entity-last-modified.mdx b/docs/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/docs/client-api/session/how-to/get-entity-last-modified.mdx +++ b/docs/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/get-tracked-entities.mdx b/docs/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/docs/client-api/session/how-to/get-tracked-entities.mdx +++ b/docs/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/ignore-entity-changes.mdx b/docs/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/docs/client-api/session/how-to/ignore-entity-changes.mdx +++ b/docs/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/perform-operations-lazily.mdx b/docs/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/docs/client-api/session/how-to/perform-operations-lazily.mdx +++ b/docs/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/refresh-entity.mdx b/docs/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/docs/client-api/session/how-to/refresh-entity.mdx +++ b/docs/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/docs/client-api/session/how-to/subscribe-to-events.mdx b/docs/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/docs/client-api/session/how-to/subscribe-to-events.mdx +++ b/docs/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/docs/client-api/session/loading-entities.mdx b/docs/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/docs/client-api/session/loading-entities.mdx +++ b/docs/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/docs/client-api/session/opening-a-session.mdx b/docs/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/docs/client-api/session/opening-a-session.mdx +++ b/docs/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/docs/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/docs/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/docs/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 76701c04da..0000000000 --- a/docs/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,962 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/docs/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/docs/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/docs/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/docs/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/docs/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index f63a3d807a..0000000000 --- a/docs/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,514 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - -* Note the following difference between the underlying search engines: - - * When using __Lucene__: - This metadata property is always available in the results. - - * When using __Corax__: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/docs/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/docs/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index 736fd7b1ba..0000000000 --- a/docs/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,537 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/docs/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/docs/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 2767086d97..0000000000 --- a/docs/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/docs/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/docs/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/docs/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/docs/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/docs/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/docs/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/docs/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/docs/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index e9e99cf398..0000000000 --- a/docs/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -| Parameter | Type | Description | -|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/docs/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/docs/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-count-query-results-php.mdx b/docs/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-count-query-results-php.mdx rename to docs/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/docs/client-api/session/querying/_how-to-count-query-results-python.mdx b/docs/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-count-query-results-python.mdx rename to docs/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/docs/client-api/session/querying/_how-to-customize-query-csharp.mdx b/docs/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-customize-query-java.mdx b/docs/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-customize-query-java.mdx rename to docs/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/docs/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-customize-query-php.mdx b/docs/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-customize-query-php.mdx rename to docs/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/docs/client-api/session/querying/_how-to-customize-query-python.mdx b/docs/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-customize-query-python.mdx rename to docs/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/docs/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-filter-by-field-java.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to docs/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/docs/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-filter-by-field-php.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to docs/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/docs/client-api/session/querying/_how-to-filter-by-field-python.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to docs/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/docs/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/docs/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/docs/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to docs/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/docs/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/docs/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to docs/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/docs/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/docs/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to docs/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..a3f3e8abc4 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,962 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..3229d3c59f --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,514 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + +* Note the following difference between the underlying search engines: + + * When using __Lucene__: + This metadata property is always available in the results. + + * When using __Corax__: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..783b4dbee8 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,537 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/docs/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to docs/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/docs/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/docs/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to docs/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/docs/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to docs/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/docs/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to docs/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/docs/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/docs/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to docs/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/docs/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to docs/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/docs/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/docs/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to docs/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/docs/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/docs/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-project-query-results-java.mdx b/docs/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-project-query-results-java.mdx rename to docs/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/docs/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-project-query-results-php.mdx b/docs/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-project-query-results-php.mdx rename to docs/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/docs/client-api/session/querying/_how-to-project-query-results-python.mdx b/docs/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-project-query-results-python.mdx rename to docs/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/docs/client-api/session/querying/_how-to-query-csharp.mdx b/docs/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-query-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-query-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-query-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-query-php.mdx b/docs/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-query-php.mdx rename to docs/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/docs/client-api/session/querying/_how-to-query-python.mdx b/docs/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-query-python.mdx rename to docs/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/docs/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/docs/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-stream-query-results-java.mdx b/docs/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to docs/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/docs/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/docs/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-use-intersect-java.mdx b/docs/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-intersect-java.mdx rename to docs/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/docs/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-use-intersect-php.mdx b/docs/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-intersect-php.mdx rename to docs/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/docs/client-api/session/querying/_how-to-use-intersect-python.mdx b/docs/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-intersect-python.mdx rename to docs/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/docs/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/docs/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to docs/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/docs/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/docs/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to docs/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/docs/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to docs/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/docs/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/docs/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to docs/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/docs/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/docs/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to docs/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/docs/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..1d4b9221d7 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/docs/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from docs/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to docs/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/docs/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/docs/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/docs/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f0354dff46 --- /dev/null +++ b/docs/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +| Parameter | Type | Description | +|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/docs/client-api/session/querying/_sort-query-results-csharp.mdx b/docs/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_sort-query-results-csharp.mdx rename to docs/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/docs/client-api/session/querying/_sort-query-results-nodejs.mdx b/docs/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/_sort-query-results-nodejs.mdx rename to docs/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/docs/client-api/session/querying/_sort-query-results-php.mdx b/docs/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from docs/client-api/session/querying/_sort-query-results-php.mdx rename to docs/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/docs/client-api/session/querying/_sort-query-results-python.mdx b/docs/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from docs/client-api/session/querying/_sort-query-results-python.mdx rename to docs/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/docs/client-api/session/querying/_vector-search-csharp.mdx b/docs/client-api/session/querying/content/_vector-search-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/_vector-search-csharp.mdx rename to docs/client-api/session/querying/content/_vector-search-csharp.mdx diff --git a/docs/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/docs/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index ced793543f..0000000000 --- a/docs/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/docs/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/docs/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/docs/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/docs/client-api/session/querying/debugging/_include-explanations-php.mdx b/docs/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/docs/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/docs/client-api/session/querying/debugging/_include-explanations-python.mdx b/docs/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/docs/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/docs/client-api/session/querying/debugging/_query-timings-csharp.mdx b/docs/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 90c08b9c95..0000000000 --- a/docs/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/docs/client-api/session/querying/debugging/_query-timings-java.mdx b/docs/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index 82050a7150..0000000000 --- a/docs/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -The `QueryTimings` object will be filled with the timings when the query returns. - -| `QueryTimings` | | | -|------------------|-----------------------------|---------------------------------------------------| -| __durationInMs__ | `long` | Total duration | -| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/docs/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/docs/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 2594955761..0000000000 --- a/docs/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,106 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/docs/client-api/session/querying/debugging/_query-timings-php.mdx b/docs/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 447455323e..0000000000 --- a/docs/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/docs/client-api/session/querying/debugging/_query-timings-python.mdx b/docs/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index a24ff39584..0000000000 --- a/docs/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/docs/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/docs/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..54a96307a9 --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/docs/client-api/session/querying/debugging/_include-explanations-java.mdx b/docs/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from docs/client-api/session/querying/debugging/_include-explanations-java.mdx rename to docs/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/docs/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/docs/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/docs/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/docs/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/docs/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/docs/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/docs/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/docs/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..87f6efdabe --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/docs/client-api/session/querying/debugging/content/_query-timings-java.mdx b/docs/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..dde738eb47 --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +The `QueryTimings` object will be filled with the timings when the query returns. + +| `QueryTimings` | | | +|------------------|-----------------------------|---------------------------------------------------| +| __durationInMs__ | `long` | Total duration | +| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/docs/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/docs/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..04c49f9a7d --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,106 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/docs/client-api/session/querying/debugging/content/_query-timings-php.mdx b/docs/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..ff61a93e87 --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/docs/client-api/session/querying/debugging/content/_query-timings-python.mdx b/docs/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..ed2089f0f5 --- /dev/null +++ b/docs/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/docs/client-api/session/querying/debugging/include-explanations.mdx b/docs/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/docs/client-api/session/querying/debugging/include-explanations.mdx +++ b/docs/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/docs/client-api/session/querying/debugging/query-timings.mdx b/docs/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/docs/client-api/session/querying/debugging/query-timings.mdx +++ b/docs/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/docs/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/docs/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/docs/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/docs/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/docs/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/docs/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to docs/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/docs/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/docs/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to docs/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/docs/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/docs/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to docs/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/docs/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/docs/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to docs/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/docs/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/docs/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to docs/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/docs/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/docs/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to docs/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/docs/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/docs/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to docs/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/docs/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/docs/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to docs/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/docs/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/docs/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to docs/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/docs/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/docs/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to docs/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/docs/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/docs/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to docs/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/docs/client-api/session/querying/document-query/how-to-use-lucene.mdx b/docs/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/docs/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/docs/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/docs/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/docs/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/docs/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/docs/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/docs/client-api/session/querying/document-query/query-vs-document-query.mdx b/docs/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/docs/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/docs/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/document-query/what-is-document-query.mdx b/docs/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/docs/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/docs/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-count-query-results.mdx b/docs/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/docs/client-api/session/querying/how-to-count-query-results.mdx +++ b/docs/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-customize-query.mdx b/docs/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/docs/client-api/session/querying/how-to-customize-query.mdx +++ b/docs/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-filter-by-field.mdx b/docs/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/docs/client-api/session/querying/how-to-filter-by-field.mdx +++ b/docs/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/docs/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/docs/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/docs/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-get-query-statistics.mdx b/docs/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/docs/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/docs/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-make-a-spatial-query.mdx b/docs/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/docs/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/docs/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/docs/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/docs/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/docs/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-perform-group-by-query.mdx b/docs/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/docs/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/docs/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-perform-queries-lazily.mdx b/docs/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/docs/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/docs/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-project-query-results.mdx b/docs/client-api/session/querying/how-to-project-query-results.mdx index 005a01c964..505ff9b85d 100644 --- a/docs/client-api/session/querying/how-to-project-query-results.mdx +++ b/docs/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-query.mdx b/docs/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/docs/client-api/session/querying/how-to-query.mdx +++ b/docs/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-stream-query-results.mdx b/docs/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/docs/client-api/session/querying/how-to-stream-query-results.mdx +++ b/docs/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-use-intersect.mdx b/docs/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/docs/client-api/session/querying/how-to-use-intersect.mdx +++ b/docs/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-use-morelikethis.mdx b/docs/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/docs/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/docs/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/docs/client-api/session/querying/how-to-work-with-suggestions.mdx b/docs/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/docs/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/docs/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/docs/client-api/session/querying/sort-query-results.mdx b/docs/client-api/session/querying/sort-query-results.mdx index a34e918743..26b8cb85a3 100644 --- a/docs/client-api/session/querying/sort-query-results.mdx +++ b/docs/client-api/session/querying/sort-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/docs/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/docs/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/docs/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/docs/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/docs/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/docs/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/docs/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/docs/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/docs/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/docs/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 5895b26e49..0000000000 --- a/docs/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,369 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/docs/client-api/session/querying/text-search/boost-search-results.mdx b/docs/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/docs/client-api/session/querying/text-search/boost-search-results.mdx +++ b/docs/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/docs/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_boost-search-results-php.mdx b/docs/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to docs/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/docs/client-api/session/querying/text-search/_boost-search-results-python.mdx b/docs/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to docs/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/docs/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/docs/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_ends-with-query-php.mdx b/docs/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to docs/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/docs/client-api/session/querying/text-search/_ends-with-query-python.mdx b/docs/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to docs/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/docs/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/docs/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_exact-match-query-java.mdx b/docs/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to docs/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/docs/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_exact-match-query-php.mdx b/docs/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to docs/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/docs/client-api/session/querying/text-search/_exact-match-query-python.mdx b/docs/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to docs/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/docs/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/docs/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_full-text-search-php.mdx b/docs/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_full-text-search-php.mdx rename to docs/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/docs/client-api/session/querying/text-search/_full-text-search-python.mdx b/docs/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_full-text-search-python.mdx rename to docs/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/docs/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/docs/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/docs/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to docs/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/docs/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/docs/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to docs/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/docs/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/docs/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to docs/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/docs/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/docs/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/docs/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/docs/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/docs/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to docs/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/docs/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/docs/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/docs/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/docs/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/docs/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/docs/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/docs/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..b672d2b64e --- /dev/null +++ b/docs/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,369 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/docs/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/docs/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_proximity-search-java.mdx b/docs/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_proximity-search-java.mdx rename to docs/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/docs/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_proximity-search-php.mdx b/docs/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_proximity-search-php.mdx rename to docs/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/docs/client-api/session/querying/text-search/_proximity-search-python.mdx b/docs/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_proximity-search-python.mdx rename to docs/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/docs/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/docs/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_starts-with-query-php.mdx b/docs/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to docs/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/docs/client-api/session/querying/text-search/_starts-with-query-python.mdx b/docs/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to docs/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/docs/client-api/session/querying/text-search/_using-regex-csharp.mdx b/docs/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to docs/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/docs/client-api/session/querying/text-search/_using-regex-java.mdx b/docs/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_using-regex-java.mdx rename to docs/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/docs/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/docs/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to docs/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/docs/client-api/session/querying/text-search/_using-regex-php.mdx b/docs/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_using-regex-php.mdx rename to docs/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/docs/client-api/session/querying/text-search/_using-regex-python.mdx b/docs/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from docs/client-api/session/querying/text-search/_using-regex-python.mdx rename to docs/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/docs/client-api/session/querying/text-search/ends-with-query.mdx b/docs/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/docs/client-api/session/querying/text-search/ends-with-query.mdx +++ b/docs/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/exact-match-query.mdx b/docs/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/docs/client-api/session/querying/text-search/exact-match-query.mdx +++ b/docs/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/full-text-search.mdx b/docs/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/docs/client-api/session/querying/text-search/full-text-search.mdx +++ b/docs/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/fuzzy-search.mdx b/docs/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/docs/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/docs/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/highlight-query-results.mdx b/docs/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/docs/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/docs/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/proximity-search.mdx b/docs/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/docs/client-api/session/querying/text-search/proximity-search.mdx +++ b/docs/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/starts-with-query.mdx b/docs/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/docs/client-api/session/querying/text-search/starts-with-query.mdx +++ b/docs/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/docs/client-api/session/querying/text-search/using-regex.mdx b/docs/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/docs/client-api/session/querying/text-search/using-regex.mdx +++ b/docs/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/docs/client-api/session/querying/vector-search.mdx b/docs/client-api/session/querying/vector-search.mdx index 49709640a7..19b0fe51a4 100644 --- a/docs/client-api/session/querying/vector-search.mdx +++ b/docs/client-api/session/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/docs/client-api/session/saving-changes.mdx b/docs/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/docs/client-api/session/saving-changes.mdx +++ b/docs/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/docs/client-api/session/storing-entities.mdx b/docs/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/docs/client-api/session/storing-entities.mdx +++ b/docs/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/docs/client-api/session/updating-entities.mdx b/docs/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/docs/client-api/session/updating-entities.mdx +++ b/docs/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/docs/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/docs/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/docs/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/docs/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/docs/client-api/setting-up-authentication-and-authorization.mdx b/docs/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/docs/client-api/setting-up-authentication-and-authorization.mdx +++ b/docs/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/docs/client-api/setting-up-default-database.mdx b/docs/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/docs/client-api/setting-up-default-database.mdx +++ b/docs/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/docs/client-api/smuggler/_what-is-smuggler-csharp.mdx b/docs/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from docs/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to docs/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/docs/client-api/smuggler/_what-is-smuggler-java.mdx b/docs/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from docs/client-api/smuggler/_what-is-smuggler-java.mdx rename to docs/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/docs/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/docs/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from docs/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to docs/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/docs/client-api/smuggler/what-is-smuggler.mdx b/docs/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/docs/client-api/smuggler/what-is-smuggler.mdx +++ b/docs/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/docs/client-api/what-is-a-document-store.mdx b/docs/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/docs/client-api/what-is-a-document-store.mdx +++ b/docs/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/docs/data-archival/_archived-documents-and-other-features-csharp.mdx b/docs/data-archival/_archived-documents-and-other-features-csharp.mdx deleted file mode 100644 index 7ec3ad6a58..0000000000 --- a/docs/data-archival/_archived-documents-and-other-features-csharp.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), - RavenDB features can detect these documents and handle them in different ways. - -* Some features, like indexes and data subscriptions, provide native support for configuring whether to: - * **Exclude** archived documents from processing, reducing index size and improving query relevance. - * **Include** only archived documents, for tasks that target archived data specifically. - * **Process both** archived and non-archived documents when needed. - -* Other features can manage archived documents differently based on their purpose. For example: - * ETL tasks can skip or selectively process archived documents. - * Archived documents can be included or excluded when exporting or importing data. - -* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. - -* Learn more below about how various RavenDB features interact with archived documents. -* In this article: - * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) - * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) - * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) - * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) - * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) - * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) - * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) - * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) - * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) - * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) - - -## Archived documents and indexing - -* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. -* Archiving documents and excluding them from indexing can be an effective way to maintain performance. - By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. - This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. -* **Configuring indexing behavior - Static indexes**: - * **At the database level or server-wide**: - To control whether static indexes process archived documents from the source collection, - set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) - configuration key at either the database level or server-wide (default: `ExcludeArchived`). - * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. - This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. - * **Per index**: - You can override this global behavior per-index directly in the index definition, using the Client API from the Studio - (see the examples below). - -* **Configuring indexing behavior - Auto indexes:** - * **At the database level or server-wide**: - To control whether auto-indexes process archived documents at the database level or server-wide, - set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). - * **Per index**: - Unlike static indexes, you cannot configure this behavior per auto-index, - because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the index. - * `IncludeArchived`: both archived and non-archived documents are processed by the index. - * `ArchivedOnly`: only archived documents are processed by the index. -##### Configuring archived document processing for a static index - from the Client API - -You can configure how a static index handles archived documents when creating the index using the Client API. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`public class Orders_ByOrderDate : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public DateTime OrderDate { get; set; } - } - - public Orders_ByOrderDate() - { - Map = orders => from order in orders - select new IndexEntry - { - OrderDate = order.OrderedAt - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByOrderDate_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - return { - OrderDate: order.OrderedAt - }; - })" - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinitionBuilder() -{ - Map = orders => from order in orders - select new { order.OrderedAt } -} - .ToIndexDefinition(new DocumentConventions()); - -indexDefinition.Name = "Orders/ByOrderDate"; - -// Configure whether the index should process data from archived documents: -// ======================================================================== -indexDefinition.ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - ArchivedDataProcessingBehavior.IncludeArchived; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - - -When a static-index is configured to include **both** archived and non-archived documents in its processing, -you can also apply custom logic based on the presence of the `@archived` metadata property. - -For example: - - - - -{`public class Orders_ByArchivedStatus : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public bool? isArchived { get; set; } - public DateTime? OrderDate { get; set; } - public string ShipToCountry { get; set; } - } - - public Orders_ByArchivedStatus() - { - Map = orders => from order in orders - let metadata = MetadataFor(order) - - // Retrieve the '@archived' metadata property from the document: - let archivedProperty = - metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) - // Alternative syntax: - // let archivedProperty = - // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] - - select new IndexEntry - { - // Index whether the document is archived: - isArchived = archivedProperty == true, - - // Index the order date only if the document is archived: - OrderDate = archivedProperty == true ? order.OrderedAt : null, - - // Index the destination country only if the document is not archived: - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByArchivedStatus_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - var metadata = metadataFor(order); - var archivedProperty = metadata['@archived']; - - var isArchived = (archivedProperty === true); - - var orderDate = isArchived ? order.OrderedAt : null; - var shipToCountry = !isArchived ? order.ShipTo.Country : null; - - return { - IsArchived: isArchived, - OrderDate: orderDate, - ShipToCountry: shipToCountry - }; - })" - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "Orders/ByArchivedStatus", - - Maps = new HashSet - { - @"from order in docs.Orders - let metadata = MetadataFor(order) - let archivedProperty = (bool?)metadata[""@archived""] - - select new - { - IsArchived = archivedProperty == true, - OrderDate = archivedProperty == true ? order.OrderedAt : null, - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }" - }, - - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - -##### Configuring archived document processing for a static index - from the Studio - -You can configure how a static index handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - -![Configure index](./assets/configure-static-index.png) - -1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, - or create a new index. -2. Scroll down and open the **Archived Data** tab. -3. Click to select how this index should process archived documents: - * **Default**: The index will use the behavior set by the global configuration. - * **Exclude Archived**: Index only non-archived documents. - * **Include Archived**: Index both archived and non-archived documents. - * **Archived Only**: Index only archived documents. - -![Processing options](./assets/processing-options.png) - - - -## Archived documents and querying - -* **Full collection queries**: - * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. - * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. - * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). - -* **Dynamic queries (auto-indexes)**: - * When making a dynamic query, RavenDB creates an auto-index to serve it. - Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. - * Once created, the auto-index retains that behavior. - Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. - * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). - -* **Querying static-indexes**: - * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. - The index behavior is determined by: - * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - - * the explicit setting in the index definition, which overrides the global configuration key. - * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. - - - -## Archived documents and subscriptions - -* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. -* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. - This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. -* **Configuring the subscription task behavior**: - * **At the database level or server-wide**: - To control whether queries in data subscription tasks process archived documents, - set the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration#subscriptionsarchiveddataprocessingbehavior) configuration key at either the database level or server-wide - (default: `ExcludeArchived`). - * **Per task**: - You can override this global behavior per data subscription task directly in the task definition, - using the Client API or from the Studio (see the examples below). -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the subscription query. - * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. - * `ArchivedOnly`: only archived documents are processed by the subscription query. -##### Configuring archived document processing for a data subscription task - from the Client API - -You can configure how a subscription task handles archived documents when creating the subscription using the Client API. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - Query = "from Orders", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - - -##### Configuring archived document processing for a data subscription task - from the Studio - -You can configure how a subscription task handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - -![Configure subscription](./assets/configure-subscription.png) - -1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, - or create a new subscription. -2. Click to select how the subscription query should process archived documents: - * **Default**: The subscription will use the behavior set by the global configuration. - * **Exclude Archived**: Process only non-archived documents. - * **Include Archived**: Process both archived and non-archived documents. - * **Archived Only**: Process only archived documents. - - - -## Archived documents and document extensions - -* **Attachments**: - * Attachments are Not archived (compressed), even if the document they belong to is archived. - -* **Counters**: - * Counters are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Time series**: - * Time series are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Revisions**: - * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. - * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. - - - -## Archived documents and smuggler (export/import) - -You can control whether archived documents are included when exporting or importing a database. -##### Export/Import archived documents - from the Client API - -[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. -By default, archived documents are **included** in the operation. - - - -In this example, exported data **excludes** archived documents: - - - -{`var exportOperation = store.Smuggler.ExportAsync( - new DatabaseSmugglerExportOptions() - \{ - // Export only non-archived documents: - IncludeArchived = false - \}, "DestinationFilePath"); -`} - - - - - - - -In this example, imported data **includes** archived documents: - - - -{`var importOperation = store.Smuggler.ImportAsync( - new DatabaseSmugglerImportOptions() - \{ - // Include archived documents in the import: - IncludeArchived = true - \}, "SourceFilePath"); -`} - - - - -##### Export archived documents - from the Studio - -![Export archived documents](./assets/export-archived-documents.png) - -1. Go to **Tasks > Export Database**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. -##### Import archived documents - from the Studio - -![Import archived documents](./assets/import-archived-documents.png) - -1. Go to **Tasks > Import Data**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. - - - -## Archived documents and expiration - -* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). - -* For example, a document can be scheduled to be archived after six months and expired after one year. - This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, - and eventually remove documents that are no longer needed. - -* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` - to schedule it for archiving and expiration, respectively: - - - -{`\{ - "Name": "Wilman Kala", - "Phone": "90-224 8858", - ... - "@metadata": \{ - "@archive-at": "2026-01-06T22:45:30.018Z", - "@expires": "2026-07-06T22:45:30.018Z", - "@collection": "Companies", - ... - \} -\} -`} - - - - - -## Archived documents and ETL - -* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) - for the existence of the `@archived: true` property, which indicates that the document is archived. - Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. - -* With [RavenDB ETL](../server/ongoing-tasks/etl/raven), documents that are archived in the source database and sent to the target - are not archived in the destination database. - -* In the following example, the ETL script checks whether the document is archived, and skips it if it is: - - - -{`var isArchived = this['@metadata']['@archived']; - -if (isArchived === true) \{ - return; // Do not process archived documents -\} - -// Transfer only non-archived documents to the target -loadToOrders(this); -`} - - - - - -## Archived documents and backup - -* Archived documents are included in database backups (both _logical backups_ and _snapshots_), - no special configuration is required. - -* When restoring a database from a backup, archived documents are restored as well, - and their archived status is preserved. - - - -## Archived documents and replication - -Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, -[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - -no special configuration is required. - - - -## Archived documents and patching - -* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: - [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). - [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). - -* Patching is used to **unarchive** documents. - See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). - -* When **cloning** an archived document using the `put` method within a patching script - (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, - and the `@archived: true` property will be removed from the cloned document. - - - - diff --git a/docs/data-archival/_enable-data-archiving-csharp.mdx b/docs/data-archival/_enable-data-archiving-csharp.mdx deleted file mode 100644 index 4b2741bca0..0000000000 --- a/docs/data-archival/_enable-data-archiving-csharp.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, data archiving is disabled. - To use the archiving feature, you must first **enable** it. - -* When configuring the feature, - you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. - -* Once enabled, the archiving task runs periodically at the configured frequency, - scanning the database for documents that have been scheduled for archival. - Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). - -* In this article: - * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) - * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) - - -## Enable archiving - from the Client API - -Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. -**Example**: - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.Send -store.Maintenance.Send(configureArchivalOp); -`} - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.SendAsync -await store.Maintenance.SendAsync(configureArchivalOp); -`} - - - -**Syntax**: - - - -{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) -`} - - - - - -{`public class DataArchivalConfiguration -\{ - public bool Disabled \{ get; set; \} - public long? ArchiveFrequencyInSec \{ get; set; \} - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | -| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | -| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | - - - -## Enable archiving - from the Studio - -![Enable archiving](./assets/enable-archiving.png) - -1. Go to **Settings > Data Archival**. -2. Toggle on to enable data archival. -3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. - Default is 60 seconds. -4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. -5. Click Save to apply your settings. - - - - diff --git a/docs/data-archival/_schedule-document-archiving-csharp.mdx b/docs/data-archival/_schedule-document-archiving-csharp.mdx deleted file mode 100644 index cd81710280..0000000000 --- a/docs/data-archival/_schedule-document-archiving-csharp.mdx +++ /dev/null @@ -1,274 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents cannot be archived directly - they must be scheduled for archival. - To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). - This can be done in several ways, as described in this article. - -* **Note**: - Just scheduling a document for archival does Not archive it at the specified time. - Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). - This task periodically scans the database for documents scheduled for archival. - The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). - -* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. - The `@archive-at` metadata property will then be replaced with `@archived: true`. - -* You can schedule documents for archival even if the archiving feature is not yet enabled. - These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. -* In this article: - * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) - * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) - * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) - * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) - - -## Schedule a SINGLE document for archiving - from the Client API - -To schedule a single document for archival from the Client API, -add the `@archive-at` property directly to the document metadata as follows: - - - - -{`using (var session = store.OpenSession()) -{ - // Load the document to schedule for archiving - var company = session.Load("companies/91-A"); - - // Access the document's metadata - var metadata = session.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - // Load the document to schedule for archiving - var company = await asyncSession.LoadAsync("companies/91-A"); - - // Access the document's metadata - var metadata = asyncSession.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - -Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - - - -## Schedule a SINGLE document for archiving - from the Studio - -* To schedule a single document for archival from the Studio: - * Open the Document view. - * Add the `@archive-at` property to the document's metadata. - * Set its value to the desired archive time in UTC format. - * Save the document. - -![Schedule a document for archiving](./assets/schedule-document-for-archiving.png) - -1. This is the `@archive-at` property that was added to the document's metadata. - E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` -2. After saving the document, the Studio displays the time remaining until the document is archived. - - - -## Schedule MULTIPLE documents for archiving - from the Client API - -* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. - -* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. - In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). - -* When the patch operation is executed, - the server will add the `@archive-at` property to the metadata of all documents that match the query filter. -**Example:** - -The following example schedules all orders that were made at least a year ago for archival. -The **patch query** filters for these older orders. -Any document matching the query is then scheduled for archival by the **patch script**. - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - // The patch query: - // ================ - from Orders - where OrderedAt < '{oldDateString}' - update {{ - // The patch script - schedule for archival: - // ========================================= - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < '{oldDateString}' - update {{ - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.archiveAt(doc, utcDateTimeString) -`} - - - -| Parameter | Type | Description | -|-----------------------|-------------|--------------------------------------------------------------------------------------| -| **doc** | `object` | The document to schedule for archiving. | -| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | - -To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). - - - -## Schedule MULTIPLE documents for archiving - from the Studio - -* To schedule multiple documents for archiving from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. - -![Schedule multiple documents for archiving](./assets/schedule-multiple-documents-for-archiving.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - - diff --git a/docs/data-archival/_unarchiving-documents-csharp.mdx b/docs/data-archival/_unarchiving-documents-csharp.mdx deleted file mode 100644 index 1f12e49710..0000000000 --- a/docs/data-archival/_unarchiving-documents-csharp.mdx +++ /dev/null @@ -1,230 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Archived documents can be unarchived at any time. - -* The archiving feature does Not need to be enabled to unarchive documents. - Any previously archived document can be unarchived, regardless of the feature's current state. - -* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. - This will not clear the internal archived status of the document. - To properly unarchive a document, use the `archived.unarchive()` method as described below. - -* In this article: - * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) - * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) - * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) - - -## Unarchive documents - from the Client API - -* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, - which targets one or more documents based on the patch query. - -* You can apply any filtering condition within the query to target only the documents you want to unarchive. - -* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents - that match the **patch query**. -**Example:** - -The following operation will unarchive ALL archived documents in the _Orders_ collection. - - - - -{`// Define the patch query string -string patchByQuery = @" - // The patch query: - // ================ - from Orders - update - { - // The patch script: - // ================= - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.unarchive(doc) -`} - - - -| Parameter | Type | Description | -|------------|----------|----------------------------| -| **doc** | `object` | The document to unarchive. | - - - -## Unarchive documents - from the Studio - -* To unarchive documents from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.unarchive()` method. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. -It will unarchive all archived documents in the _Orders_ collection. - -![Unarchive documents](./assets/unarchive-documents.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - -## Unarchiving documents with index-based patch queries - -* When running a patch query to unarchive documents over an index, - you need to consider the index configuration regarding archived documents. - -* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - - because those documents are not included in the index. - As a result, no documents will be unarchived by the patch operation. - -* For example, the following patch query uses a dynamic query that creates an auto-index. - If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, - then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - - and the patch operation will not unarchive any documents. - - - -{`string patchByQuery = @" - // This filtering query creates an auto-index: - // =========================================== - from Orders - where ShipTo.Country == 'USA' - update - \{ - archived.unarchive(this) - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - -Two possible workarounds are: - -1. **Configure the index to include archived documents**: - This ensures archived documents are included in the index and can be matched by the patch query. - Use this option only if including archived documents in the index aligns with your indexing strategy. - - **For auto-indexes**: - Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. - **For static-indexes**: - Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, - or - configure the definition of the specific static-index to include archived documents. - See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). - -2. **Use a collection query instead of an index query**: - Run a simple collection-based query that does not rely on an index. - Apply your filtering logic inside the patch script to unarchive only the relevant documents. - - For example: - - -{`string patchByQuery = @" - // Perform a collection query: - // =========================== - from Orders as order - update - \{ - // Filter documents inside the script: - // =================================== - if (order.ShipTo.City == 'New York') - \{ - archived.unarchive(this) - \} - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - - - - - diff --git a/docs/data-archival/archived-documents-and-other-features.mdx b/docs/data-archival/archived-documents-and-other-features.mdx index 6cf644a121..6e66d0d452 100644 --- a/docs/data-archival/archived-documents-and-other-features.mdx +++ b/docs/data-archival/archived-documents-and-other-features.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ArchivedDocumentsAndOtherFeaturesCsharp from './_archived-documents-and-other-features-csharp.mdx'; +import ArchivedDocumentsAndOtherFeaturesCsharp from './content/_archived-documents-and-other-features-csharp.mdx'; diff --git a/docs/data-archival/content/_archived-documents-and-other-features-csharp.mdx b/docs/data-archival/content/_archived-documents-and-other-features-csharp.mdx new file mode 100644 index 0000000000..78151712fd --- /dev/null +++ b/docs/data-archival/content/_archived-documents-and-other-features-csharp.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), + RavenDB features can detect these documents and handle them in different ways. + +* Some features, like indexes and data subscriptions, provide native support for configuring whether to: + * **Exclude** archived documents from processing, reducing index size and improving query relevance. + * **Include** only archived documents, for tasks that target archived data specifically. + * **Process both** archived and non-archived documents when needed. + +* Other features can manage archived documents differently based on their purpose. For example: + * ETL tasks can skip or selectively process archived documents. + * Archived documents can be included or excluded when exporting or importing data. + +* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. + +* Learn more below about how various RavenDB features interact with archived documents. +* In this article: + * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) + * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) + * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) + * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) + * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) + * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) + * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) + * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) + * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) + * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) + + +## Archived documents and indexing + +* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. +* Archiving documents and excluding them from indexing can be an effective way to maintain performance. + By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. + This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. +* **Configuring indexing behavior - Static indexes**: + * **At the database level or server-wide**: + To control whether static indexes process archived documents from the source collection, + set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) + configuration key at either the database level or server-wide (default: `ExcludeArchived`). + * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. + This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. + * **Per index**: + You can override this global behavior per-index directly in the index definition, using the Client API from the Studio + (see the examples below). + +* **Configuring indexing behavior - Auto indexes:** + * **At the database level or server-wide**: + To control whether auto-indexes process archived documents at the database level or server-wide, + set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). + * **Per index**: + Unlike static indexes, you cannot configure this behavior per auto-index, + because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the index. + * `IncludeArchived`: both archived and non-archived documents are processed by the index. + * `ArchivedOnly`: only archived documents are processed by the index. +##### Configuring archived document processing for a static index - from the Client API + +You can configure how a static index handles archived documents when creating the index using the Client API. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`public class Orders_ByOrderDate : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public DateTime OrderDate { get; set; } + } + + public Orders_ByOrderDate() + { + Map = orders => from order in orders + select new IndexEntry + { + OrderDate = order.OrderedAt + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByOrderDate_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + return { + OrderDate: order.OrderedAt + }; + })" + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinitionBuilder() +{ + Map = orders => from order in orders + select new { order.OrderedAt } +} + .ToIndexDefinition(new DocumentConventions()); + +indexDefinition.Name = "Orders/ByOrderDate"; + +// Configure whether the index should process data from archived documents: +// ======================================================================== +indexDefinition.ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + ArchivedDataProcessingBehavior.IncludeArchived; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + + +When a static-index is configured to include **both** archived and non-archived documents in its processing, +you can also apply custom logic based on the presence of the `@archived` metadata property. + +For example: + + + + +{`public class Orders_ByArchivedStatus : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public bool? isArchived { get; set; } + public DateTime? OrderDate { get; set; } + public string ShipToCountry { get; set; } + } + + public Orders_ByArchivedStatus() + { + Map = orders => from order in orders + let metadata = MetadataFor(order) + + // Retrieve the '@archived' metadata property from the document: + let archivedProperty = + metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) + // Alternative syntax: + // let archivedProperty = + // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] + + select new IndexEntry + { + // Index whether the document is archived: + isArchived = archivedProperty == true, + + // Index the order date only if the document is archived: + OrderDate = archivedProperty == true ? order.OrderedAt : null, + + // Index the destination country only if the document is not archived: + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByArchivedStatus_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + var metadata = metadataFor(order); + var archivedProperty = metadata['@archived']; + + var isArchived = (archivedProperty === true); + + var orderDate = isArchived ? order.OrderedAt : null; + var shipToCountry = !isArchived ? order.ShipTo.Country : null; + + return { + IsArchived: isArchived, + OrderDate: orderDate, + ShipToCountry: shipToCountry + }; + })" + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "Orders/ByArchivedStatus", + + Maps = new HashSet + { + @"from order in docs.Orders + let metadata = MetadataFor(order) + let archivedProperty = (bool?)metadata[""@archived""] + + select new + { + IsArchived = archivedProperty == true, + OrderDate = archivedProperty == true ? order.OrderedAt : null, + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }" + }, + + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + +##### Configuring archived document processing for a static index - from the Studio + +You can configure how a static index handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + +![Configure index](../assets/configure-static-index.png) + +1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, + or create a new index. +2. Scroll down and open the **Archived Data** tab. +3. Click to select how this index should process archived documents: + * **Default**: The index will use the behavior set by the global configuration. + * **Exclude Archived**: Index only non-archived documents. + * **Include Archived**: Index both archived and non-archived documents. + * **Archived Only**: Index only archived documents. + +![Processing options](../assets/processing-options.png) + + + +## Archived documents and querying + +* **Full collection queries**: + * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. + * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. + * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). + +* **Dynamic queries (auto-indexes)**: + * When making a dynamic query, RavenDB creates an auto-index to serve it. + Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. + * Once created, the auto-index retains that behavior. + Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. + * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). + +* **Querying static-indexes**: + * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. + The index behavior is determined by: + * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - + * the explicit setting in the index definition, which overrides the global configuration key. + * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. + + + +## Archived documents and subscriptions + +* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. +* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. + This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. +* **Configuring the subscription task behavior**: + * **At the database level or server-wide**: + To control whether queries in data subscription tasks process archived documents, + set the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration#subscriptionsarchiveddataprocessingbehavior) configuration key at either the database level or server-wide + (default: `ExcludeArchived`). + * **Per task**: + You can override this global behavior per data subscription task directly in the task definition, + using the Client API or from the Studio (see the examples below). +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the subscription query. + * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. + * `ArchivedOnly`: only archived documents are processed by the subscription query. +##### Configuring archived document processing for a data subscription task - from the Client API + +You can configure how a subscription task handles archived documents when creating the subscription using the Client API. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + Query = "from Orders", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + + +##### Configuring archived document processing for a data subscription task - from the Studio + +You can configure how a subscription task handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + +![Configure subscription](../assets/configure-subscription.png) + +1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, + or create a new subscription. +2. Click to select how the subscription query should process archived documents: + * **Default**: The subscription will use the behavior set by the global configuration. + * **Exclude Archived**: Process only non-archived documents. + * **Include Archived**: Process both archived and non-archived documents. + * **Archived Only**: Process only archived documents. + + + +## Archived documents and document extensions + +* **Attachments**: + * Attachments are Not archived (compressed), even if the document they belong to is archived. + +* **Counters**: + * Counters are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Time series**: + * Time series are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Revisions**: + * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. + * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. + + + +## Archived documents and smuggler (export/import) + +You can control whether archived documents are included when exporting or importing a database. +##### Export/Import archived documents - from the Client API + +[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. +By default, archived documents are **included** in the operation. + + + +In this example, exported data **excludes** archived documents: + + + +{`var exportOperation = store.Smuggler.ExportAsync( + new DatabaseSmugglerExportOptions() + \{ + // Export only non-archived documents: + IncludeArchived = false + \}, "DestinationFilePath"); +`} + + + + + + + +In this example, imported data **includes** archived documents: + + + +{`var importOperation = store.Smuggler.ImportAsync( + new DatabaseSmugglerImportOptions() + \{ + // Include archived documents in the import: + IncludeArchived = true + \}, "SourceFilePath"); +`} + + + + +##### Export archived documents - from the Studio + +![Export archived documents](../assets/export-archived-documents.png) + +1. Go to **Tasks > Export Database**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. +##### Import archived documents - from the Studio + +![Import archived documents](../assets/import-archived-documents.png) + +1. Go to **Tasks > Import Data**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. + + + +## Archived documents and expiration + +* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). + +* For example, a document can be scheduled to be archived after six months and expired after one year. + This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, + and eventually remove documents that are no longer needed. + +* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` + to schedule it for archiving and expiration, respectively: + + + +{`\{ + "Name": "Wilman Kala", + "Phone": "90-224 8858", + ... + "@metadata": \{ + "@archive-at": "2026-01-06T22:45:30.018Z", + "@expires": "2026-07-06T22:45:30.018Z", + "@collection": "Companies", + ... + \} +\} +`} + + + + + +## Archived documents and ETL + +* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) + for the existence of the `@archived: true` property, which indicates that the document is archived. + Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. + +* With [RavenDB ETL](../server/ongoing-tasks/etl/raven), documents that are archived in the source database and sent to the target + are not archived in the destination database. + +* In the following example, the ETL script checks whether the document is archived, and skips it if it is: + + + +{`var isArchived = this['@metadata']['@archived']; + +if (isArchived === true) \{ + return; // Do not process archived documents +\} + +// Transfer only non-archived documents to the target +loadToOrders(this); +`} + + + + + +## Archived documents and backup + +* Archived documents are included in database backups (both _logical backups_ and _snapshots_), + no special configuration is required. + +* When restoring a database from a backup, archived documents are restored as well, + and their archived status is preserved. + + + +## Archived documents and replication + +Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, +[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - +no special configuration is required. + + + +## Archived documents and patching + +* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: + [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). + [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). + +* Patching is used to **unarchive** documents. + See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). + +* When **cloning** an archived document using the `put` method within a patching script + (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, + and the `@archived: true` property will be removed from the cloned document. + + + + diff --git a/docs/data-archival/content/_enable-data-archiving-csharp.mdx b/docs/data-archival/content/_enable-data-archiving-csharp.mdx new file mode 100644 index 0000000000..cdcdfecd0f --- /dev/null +++ b/docs/data-archival/content/_enable-data-archiving-csharp.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, data archiving is disabled. + To use the archiving feature, you must first **enable** it. + +* When configuring the feature, + you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. + +* Once enabled, the archiving task runs periodically at the configured frequency, + scanning the database for documents that have been scheduled for archival. + Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). + +* In this article: + * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) + * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) + + +## Enable archiving - from the Client API + +Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. +**Example**: + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.Send +store.Maintenance.Send(configureArchivalOp); +`} + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.SendAsync +await store.Maintenance.SendAsync(configureArchivalOp); +`} + + + +**Syntax**: + + + +{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) +`} + + + + + +{`public class DataArchivalConfiguration +\{ + public bool Disabled \{ get; set; \} + public long? ArchiveFrequencyInSec \{ get; set; \} + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | +| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | +| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | + + + +## Enable archiving - from the Studio + +![Enable archiving](../assets/enable-archiving.png) + +1. Go to **Settings > Data Archival**. +2. Toggle on to enable data archival. +3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. + Default is 60 seconds. +4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. +5. Click Save to apply your settings. + + + + diff --git a/docs/data-archival/content/_schedule-document-archiving-csharp.mdx b/docs/data-archival/content/_schedule-document-archiving-csharp.mdx new file mode 100644 index 0000000000..0414d08e3f --- /dev/null +++ b/docs/data-archival/content/_schedule-document-archiving-csharp.mdx @@ -0,0 +1,274 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents cannot be archived directly - they must be scheduled for archival. + To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). + This can be done in several ways, as described in this article. + +* **Note**: + Just scheduling a document for archival does Not archive it at the specified time. + Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). + This task periodically scans the database for documents scheduled for archival. + The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). + +* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. + The `@archive-at` metadata property will then be replaced with `@archived: true`. + +* You can schedule documents for archival even if the archiving feature is not yet enabled. + These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. +* In this article: + * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) + * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) + * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) + * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) + + +## Schedule a SINGLE document for archiving - from the Client API + +To schedule a single document for archival from the Client API, +add the `@archive-at` property directly to the document metadata as follows: + + + + +{`using (var session = store.OpenSession()) +{ + // Load the document to schedule for archiving + var company = session.Load("companies/91-A"); + + // Access the document's metadata + var metadata = session.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + // Load the document to schedule for archiving + var company = await asyncSession.LoadAsync("companies/91-A"); + + // Access the document's metadata + var metadata = asyncSession.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + +Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + + + +## Schedule a SINGLE document for archiving - from the Studio + +* To schedule a single document for archival from the Studio: + * Open the Document view. + * Add the `@archive-at` property to the document's metadata. + * Set its value to the desired archive time in UTC format. + * Save the document. + +![Schedule a document for archiving](../assets/schedule-document-for-archiving.png) + +1. This is the `@archive-at` property that was added to the document's metadata. + E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` +2. After saving the document, the Studio displays the time remaining until the document is archived. + + + +## Schedule MULTIPLE documents for archiving - from the Client API + +* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. + +* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. + In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). + +* When the patch operation is executed, + the server will add the `@archive-at` property to the metadata of all documents that match the query filter. +**Example:** + +The following example schedules all orders that were made at least a year ago for archival. +The **patch query** filters for these older orders. +Any document matching the query is then scheduled for archival by the **patch script**. + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + // The patch query: + // ================ + from Orders + where OrderedAt < '{oldDateString}' + update {{ + // The patch script - schedule for archival: + // ========================================= + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < '{oldDateString}' + update {{ + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.archiveAt(doc, utcDateTimeString) +`} + + + +| Parameter | Type | Description | +|-----------------------|-------------|--------------------------------------------------------------------------------------| +| **doc** | `object` | The document to schedule for archiving. | +| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | + +To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). + + + +## Schedule MULTIPLE documents for archiving - from the Studio + +* To schedule multiple documents for archiving from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. + +![Schedule multiple documents for archiving](../assets/schedule-multiple-documents-for-archiving.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + + diff --git a/docs/data-archival/content/_unarchiving-documents-csharp.mdx b/docs/data-archival/content/_unarchiving-documents-csharp.mdx new file mode 100644 index 0000000000..faac23a4e8 --- /dev/null +++ b/docs/data-archival/content/_unarchiving-documents-csharp.mdx @@ -0,0 +1,230 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Archived documents can be unarchived at any time. + +* The archiving feature does Not need to be enabled to unarchive documents. + Any previously archived document can be unarchived, regardless of the feature's current state. + +* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. + This will not clear the internal archived status of the document. + To properly unarchive a document, use the `archived.unarchive()` method as described below. + +* In this article: + * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) + * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) + * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) + + +## Unarchive documents - from the Client API + +* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, + which targets one or more documents based on the patch query. + +* You can apply any filtering condition within the query to target only the documents you want to unarchive. + +* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents + that match the **patch query**. +**Example:** + +The following operation will unarchive ALL archived documents in the _Orders_ collection. + + + + +{`// Define the patch query string +string patchByQuery = @" + // The patch query: + // ================ + from Orders + update + { + // The patch script: + // ================= + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.unarchive(doc) +`} + + + +| Parameter | Type | Description | +|------------|----------|----------------------------| +| **doc** | `object` | The document to unarchive. | + + + +## Unarchive documents - from the Studio + +* To unarchive documents from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.unarchive()` method. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. +It will unarchive all archived documents in the _Orders_ collection. + +![Unarchive documents](../assets/unarchive-documents.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + +## Unarchiving documents with index-based patch queries + +* When running a patch query to unarchive documents over an index, + you need to consider the index configuration regarding archived documents. + +* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - + because those documents are not included in the index. + As a result, no documents will be unarchived by the patch operation. + +* For example, the following patch query uses a dynamic query that creates an auto-index. + If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, + then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - + and the patch operation will not unarchive any documents. + + + +{`string patchByQuery = @" + // This filtering query creates an auto-index: + // =========================================== + from Orders + where ShipTo.Country == 'USA' + update + \{ + archived.unarchive(this) + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + +Two possible workarounds are: + +1. **Configure the index to include archived documents**: + This ensures archived documents are included in the index and can be matched by the patch query. + Use this option only if including archived documents in the index aligns with your indexing strategy. + + **For auto-indexes**: + Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. + **For static-indexes**: + Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, + or - configure the definition of the specific static-index to include archived documents. + See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). + +2. **Use a collection query instead of an index query**: + Run a simple collection-based query that does not rely on an index. + Apply your filtering logic inside the patch script to unarchive only the relevant documents. + + For example: + + +{`string patchByQuery = @" + // Perform a collection query: + // =========================== + from Orders as order + update + \{ + // Filter documents inside the script: + // =================================== + if (order.ShipTo.City == 'New York') + \{ + archived.unarchive(this) + \} + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + + + + + diff --git a/docs/data-archival/enable-data-archiving.mdx b/docs/data-archival/enable-data-archiving.mdx index 5792991f3d..8b1d5eb068 100644 --- a/docs/data-archival/enable-data-archiving.mdx +++ b/docs/data-archival/enable-data-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableDataArchivingCsharp from './_enable-data-archiving-csharp.mdx'; +import EnableDataArchivingCsharp from './content/_enable-data-archiving-csharp.mdx'; diff --git a/docs/data-archival/schedule-document-archiving.mdx b/docs/data-archival/schedule-document-archiving.mdx index c22e6a21ed..09b032fc17 100644 --- a/docs/data-archival/schedule-document-archiving.mdx +++ b/docs/data-archival/schedule-document-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ScheduleDocumentArchivingCsharp from './_schedule-document-archiving-csharp.mdx'; +import ScheduleDocumentArchivingCsharp from './content/_schedule-document-archiving-csharp.mdx'; diff --git a/docs/data-archival/unarchiving-documents.mdx b/docs/data-archival/unarchiving-documents.mdx index 808769d015..89afcf916d 100644 --- a/docs/data-archival/unarchiving-documents.mdx +++ b/docs/data-archival/unarchiving-documents.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UnarchivingDocumentsCsharp from './_unarchiving-documents-csharp.mdx'; +import UnarchivingDocumentsCsharp from './content/_unarchiving-documents-csharp.mdx'; diff --git a/docs/document-extensions/counters/_counters-and-other-features-csharp.mdx b/docs/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to docs/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/docs/document-extensions/counters/_counters-and-other-features-java.mdx b/docs/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from docs/document-extensions/counters/_counters-and-other-features-java.mdx rename to docs/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/docs/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/docs/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to docs/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/docs/document-extensions/counters/_counters-and-other-features-php.mdx b/docs/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from docs/document-extensions/counters/_counters-and-other-features-php.mdx rename to docs/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/docs/document-extensions/counters/_counters-and-other-features-python.mdx b/docs/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from docs/document-extensions/counters/_counters-and-other-features-python.mdx rename to docs/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/docs/document-extensions/counters/_create-or-modify-csharp.mdx b/docs/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_create-or-modify-csharp.mdx rename to docs/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/docs/document-extensions/counters/_create-or-modify-java.mdx b/docs/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from docs/document-extensions/counters/_create-or-modify-java.mdx rename to docs/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/docs/document-extensions/counters/_create-or-modify-nodejs.mdx b/docs/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_create-or-modify-nodejs.mdx rename to docs/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/docs/document-extensions/counters/_create-or-modify-php.mdx b/docs/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from docs/document-extensions/counters/_create-or-modify-php.mdx rename to docs/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/docs/document-extensions/counters/_create-or-modify-python.mdx b/docs/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from docs/document-extensions/counters/_create-or-modify-python.mdx rename to docs/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/docs/document-extensions/counters/_delete-csharp.mdx b/docs/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_delete-csharp.mdx rename to docs/document-extensions/counters/content/_delete-csharp.mdx diff --git a/docs/document-extensions/counters/_delete-java.mdx b/docs/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from docs/document-extensions/counters/_delete-java.mdx rename to docs/document-extensions/counters/content/_delete-java.mdx diff --git a/docs/document-extensions/counters/_delete-nodejs.mdx b/docs/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_delete-nodejs.mdx rename to docs/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/docs/document-extensions/counters/_delete-php.mdx b/docs/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from docs/document-extensions/counters/_delete-php.mdx rename to docs/document-extensions/counters/content/_delete-php.mdx diff --git a/docs/document-extensions/counters/_delete-python.mdx b/docs/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from docs/document-extensions/counters/_delete-python.mdx rename to docs/document-extensions/counters/content/_delete-python.mdx diff --git a/docs/document-extensions/counters/_including-counters-csharp.mdx b/docs/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_including-counters-csharp.mdx rename to docs/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/docs/document-extensions/counters/_including-counters-java.mdx b/docs/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from docs/document-extensions/counters/_including-counters-java.mdx rename to docs/document-extensions/counters/content/_including-counters-java.mdx diff --git a/docs/document-extensions/counters/_including-counters-nodejs.mdx b/docs/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_including-counters-nodejs.mdx rename to docs/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/docs/document-extensions/counters/_including-counters-php.mdx b/docs/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from docs/document-extensions/counters/_including-counters-php.mdx rename to docs/document-extensions/counters/content/_including-counters-php.mdx diff --git a/docs/document-extensions/counters/_including-counters-python.mdx b/docs/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from docs/document-extensions/counters/_including-counters-python.mdx rename to docs/document-extensions/counters/content/_including-counters-python.mdx diff --git a/docs/document-extensions/counters/_indexing-csharp.mdx b/docs/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_indexing-csharp.mdx rename to docs/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/docs/document-extensions/counters/_indexing-java.mdx b/docs/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from docs/document-extensions/counters/_indexing-java.mdx rename to docs/document-extensions/counters/content/_indexing-java.mdx diff --git a/docs/document-extensions/counters/_indexing-nodejs.mdx b/docs/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_indexing-nodejs.mdx rename to docs/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/docs/document-extensions/counters/_indexing-php.mdx b/docs/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from docs/document-extensions/counters/_indexing-php.mdx rename to docs/document-extensions/counters/content/_indexing-php.mdx diff --git a/docs/document-extensions/counters/_indexing-python.mdx b/docs/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from docs/document-extensions/counters/_indexing-python.mdx rename to docs/document-extensions/counters/content/_indexing-python.mdx diff --git a/docs/document-extensions/counters/_overview-csharp.mdx b/docs/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_overview-csharp.mdx rename to docs/document-extensions/counters/content/_overview-csharp.mdx diff --git a/docs/document-extensions/counters/_overview-java.mdx b/docs/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from docs/document-extensions/counters/_overview-java.mdx rename to docs/document-extensions/counters/content/_overview-java.mdx diff --git a/docs/document-extensions/counters/_overview-nodejs.mdx b/docs/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_overview-nodejs.mdx rename to docs/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/docs/document-extensions/counters/_overview-php.mdx b/docs/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from docs/document-extensions/counters/_overview-php.mdx rename to docs/document-extensions/counters/content/_overview-php.mdx diff --git a/docs/document-extensions/counters/_overview-python.mdx b/docs/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from docs/document-extensions/counters/_overview-python.mdx rename to docs/document-extensions/counters/content/_overview-python.mdx diff --git a/docs/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/docs/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from docs/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to docs/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/docs/document-extensions/counters/_retrieve-counter-values-java.mdx b/docs/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from docs/document-extensions/counters/_retrieve-counter-values-java.mdx rename to docs/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/docs/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/docs/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from docs/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to docs/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/docs/document-extensions/counters/_retrieve-counter-values-php.mdx b/docs/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from docs/document-extensions/counters/_retrieve-counter-values-php.mdx rename to docs/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/docs/document-extensions/counters/_retrieve-counter-values-python.mdx b/docs/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from docs/document-extensions/counters/_retrieve-counter-values-python.mdx rename to docs/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/docs/document-extensions/counters/counters-and-other-features.mdx b/docs/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/docs/document-extensions/counters/counters-and-other-features.mdx +++ b/docs/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/docs/document-extensions/counters/create-or-modify.mdx b/docs/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/docs/document-extensions/counters/create-or-modify.mdx +++ b/docs/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/docs/document-extensions/counters/delete.mdx b/docs/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/docs/document-extensions/counters/delete.mdx +++ b/docs/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/docs/document-extensions/counters/including-counters.mdx b/docs/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/docs/document-extensions/counters/including-counters.mdx +++ b/docs/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/docs/document-extensions/counters/indexing.mdx b/docs/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/docs/document-extensions/counters/indexing.mdx +++ b/docs/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/docs/document-extensions/counters/overview.mdx b/docs/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/docs/document-extensions/counters/overview.mdx +++ b/docs/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/document-extensions/counters/retrieve-counter-values.mdx b/docs/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/docs/document-extensions/counters/retrieve-counter-values.mdx +++ b/docs/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/_overview-csharp.mdx b/docs/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 0f0c9f41b9..0000000000 --- a/docs/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,327 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/docs/document-extensions/revisions/_overview-nodejs.mdx b/docs/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index c51d9e1b8f..0000000000 --- a/docs/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,324 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/docs/document-extensions/revisions/_overview-python.mdx b/docs/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 8cb585b701..0000000000 --- a/docs/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,287 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/docs/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/docs/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 2b22fdf186..0000000000 --- a/docs/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/docs/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/docs/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 942c5c6af4..0000000000 --- a/docs/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/docs/document-extensions/revisions/_revisions-and-other-features-php.mdx b/docs/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index f97f66bcf2..0000000000 --- a/docs/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/docs/document-extensions/revisions/_revisions-and-other-features-python.mdx b/docs/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index abf4b461d0..0000000000 --- a/docs/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/docs/document-extensions/revisions/client-api/_overview-csharp.mdx b/docs/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/_overview-csharp.mdx rename to docs/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/_overview-java.mdx b/docs/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/_overview-java.mdx rename to docs/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/docs/document-extensions/revisions/client-api/_overview-nodejs.mdx b/docs/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to docs/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/_overview-php.mdx b/docs/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/_overview-php.mdx rename to docs/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/docs/document-extensions/revisions/client-api/_overview-python.mdx b/docs/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/_overview-python.mdx rename to docs/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/docs/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/docs/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/docs/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/docs/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/docs/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/docs/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx b/docs/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/docs/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/docs/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/docs/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/docs/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to docs/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/docs/document-extensions/revisions/client-api/operations/delete-revisions.mdx b/docs/document-extensions/revisions/client-api/operations/delete-revisions.mdx index 52d57a6d9e..6ac42ce584 100644 --- a/docs/document-extensions/revisions/client-api/operations/delete-revisions.mdx +++ b/docs/document-extensions/revisions/client-api/operations/delete-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteRevisionsCsharp from './_delete-revisions-csharp.mdx'; +import DeleteRevisionsCsharp from './content/_delete-revisions-csharp.mdx'; diff --git a/docs/document-extensions/revisions/client-api/operations/get-revisions.mdx b/docs/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/docs/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/docs/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/overview.mdx b/docs/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/docs/document-extensions/revisions/client-api/overview.mdx +++ b/docs/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/docs/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to docs/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/docs/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to docs/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_counting-php.mdx b/docs/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_counting-php.mdx rename to docs/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_counting-python.mdx b/docs/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_counting-python.mdx rename to docs/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_including-csharp.mdx b/docs/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to docs/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/docs/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to docs/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_including-php.mdx b/docs/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_including-php.mdx rename to docs/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/docs/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to docs/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_loading-java.mdx b/docs/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_loading-java.mdx rename to docs/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/docs/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to docs/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_loading-php.mdx b/docs/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_loading-php.mdx rename to docs/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/docs/document-extensions/revisions/client-api/session/_loading-python.mdx b/docs/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from docs/document-extensions/revisions/client-api/session/_loading-python.mdx rename to docs/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/docs/document-extensions/revisions/client-api/session/counting.mdx b/docs/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/docs/document-extensions/revisions/client-api/session/counting.mdx +++ b/docs/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/session/including.mdx b/docs/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/docs/document-extensions/revisions/client-api/session/including.mdx +++ b/docs/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/client-api/session/loading.mdx b/docs/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/docs/document-extensions/revisions/client-api/session/loading.mdx +++ b/docs/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/content/_overview-csharp.mdx b/docs/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..3adf41e824 --- /dev/null +++ b/docs/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,327 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/docs/document-extensions/revisions/content/_overview-nodejs.mdx b/docs/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..60af21c283 --- /dev/null +++ b/docs/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,324 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/docs/document-extensions/revisions/content/_overview-python.mdx b/docs/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..ad06ca3084 --- /dev/null +++ b/docs/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,287 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/docs/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/docs/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..d2aee1eea5 --- /dev/null +++ b/docs/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/docs/document-extensions/revisions/_revisions-and-other-features-java.mdx b/docs/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from docs/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to docs/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/docs/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/docs/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..a22e0c2302 --- /dev/null +++ b/docs/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/docs/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/docs/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6ed3da3b54 --- /dev/null +++ b/docs/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/docs/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/docs/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..57c39fb37e --- /dev/null +++ b/docs/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/overview) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/docs/document-extensions/revisions/overview.mdx b/docs/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/docs/document-extensions/revisions/overview.mdx +++ b/docs/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx b/docs/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx deleted file mode 100644 index 1ca0053750..0000000000 --- a/docs/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx +++ /dev/null @@ -1,221 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ContentFrame from '@site/src/components/ContentFrame'; -import Panel from '@site/src/components/Panel'; - - - -* This article describes how to revert specific documents to **specific revisions**. - To revert documents from all collections (or from selected collections) to a **specific point in time**, - see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). - -* In this article: - * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) - * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) - * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) - * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) - * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) - - - - - -* When reverting to a specific revision, - the document content will be overwritten by the content of the specified revision. - -* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: - * **When revisions are ENABLED**: - Reverting the document creates a new revision containing the content of the target revision. - * **When revisions are DISABLED**: - The document is reverted to the target revision without creating a new revision. - -* In addition to the document itself, reverting will impact _Document Extensions_ as follows: - * **Attachments**: - If the target revision owns attachments, they are restored to their state when the revision was created. - * **Counters**: - If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. - * **Time series**: - Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). - - - - - -* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. - -* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). - To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). - -* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. - The document content will be overwritten by the content of the specified revision. - -* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. - -* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, - the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. - ---- - -### How to obtain a revision's change-vector: - -The change-vector of a revision can be obtained via: - - * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) - * Or from the document view in the Studio - -![Get revision CV](./assets/get-cv-for-revision.png) - -1. Go to the Revisions tab in the document view. -2. Click a revision to view -3. The document view will display the content of the revision. - This top label indicates that you are viewing a revision and not the current document. -4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. - - - - - -Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. -In this example, we revert document _orders/1-A_ to its very first revision. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "Orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); -} -``` - - - - - - - -You can use the operation to revert multiple documents. -Note: The documents do not need to belong to the same collection. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - var revisionsMetadata2 = session.Advanced.Revisions - .GetMetadataFor(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "orders/1-A"); - var revisionsMetadata2 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - - - - - - -### `RevertRevisionsByIdOperation` - - -```csharp -Available overloads: -==================== -public RevertRevisionsByIdOperation(string id, string cv); -public RevertRevisionsByIdOperation(Dictionary idToChangeVector); -``` - - -| Parameter | Type | Description | -|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| **id** | `string` | The ID of the document to revert. | -| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | -| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | - - \ No newline at end of file diff --git a/docs/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx b/docs/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx new file mode 100644 index 0000000000..df41e24beb --- /dev/null +++ b/docs/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx @@ -0,0 +1,221 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* This article describes how to revert specific documents to **specific revisions**. + To revert documents from all collections (or from selected collections) to a **specific point in time**, + see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). + +* In this article: + * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) + * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) + * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) + * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) + * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) + + + + + +* When reverting to a specific revision, + the document content will be overwritten by the content of the specified revision. + +* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: + * **When revisions are ENABLED**: + Reverting the document creates a new revision containing the content of the target revision. + * **When revisions are DISABLED**: + The document is reverted to the target revision without creating a new revision. + +* In addition to the document itself, reverting will impact _Document Extensions_ as follows: + * **Attachments**: + If the target revision owns attachments, they are restored to their state when the revision was created. + * **Counters**: + If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. + * **Time series**: + Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). + + + + + +* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. + +* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). + To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). + +* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. + The document content will be overwritten by the content of the specified revision. + +* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. + +* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, + the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. + +--- + +### How to obtain a revision's change-vector: + +The change-vector of a revision can be obtained via: + + * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) + * Or from the document view in the Studio + +![Get revision CV](../assets/get-cv-for-revision.png) + +1. Go to the Revisions tab in the document view. +2. Click a revision to view +3. The document view will display the content of the revision. + This top label indicates that you are viewing a revision and not the current document. +4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. + + + + + +Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. +In this example, we revert document _orders/1-A_ to its very first revision. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "Orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); +} +``` + + + + + + + +You can use the operation to revert multiple documents. +Note: The documents do not need to belong to the same collection. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + var revisionsMetadata2 = session.Advanced.Revisions + .GetMetadataFor(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "orders/1-A"); + var revisionsMetadata2 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + + + + + + +### `RevertRevisionsByIdOperation` + + +```csharp +Available overloads: +==================== +public RevertRevisionsByIdOperation(string id, string cv); +public RevertRevisionsByIdOperation(Dictionary idToChangeVector); +``` + + +| Parameter | Type | Description | +|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| **id** | `string` | The ID of the document to revert. | +| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | +| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | + + \ No newline at end of file diff --git a/docs/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx b/docs/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx index 041ad50de9..3586680073 100644 --- a/docs/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx +++ b/docs/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevertDocumentsToSpecificRevisionsCsharp from './_revert-documents-to-specific-revisions-csharp.mdx'; +import RevertDocumentsToSpecificRevisionsCsharp from './content/_revert-documents-to-specific-revisions-csharp.mdx'; diff --git a/docs/document-extensions/revisions/revisions-and-other-features.mdx b/docs/document-extensions/revisions/revisions-and-other-features.mdx index b385a11eb2..15eec0f88a 100644 --- a/docs/document-extensions/revisions/revisions-and-other-features.mdx +++ b/docs/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/docs/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 5972ad8ca5..0000000000 --- a/docs/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,300 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/docs/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/docs/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 2c0c4c1a5b..0000000000 --- a/docs/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,257 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/docs/document-extensions/timeseries/_rollup-and-retention-php.mdx b/docs/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index af9e9480f6..0000000000 --- a/docs/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/docs/document-extensions/timeseries/_rollup-and-retention-python.mdx b/docs/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index aa992fed57..0000000000 --- a/docs/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,309 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/docs/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/docs/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/docs/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/docs/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/docs/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/docs/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/docs/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/docs/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/docs/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/docs/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/docs/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/docs/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/docs/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/docs/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/docs/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/docs/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/docs/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to docs/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/docs/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/docs/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to docs/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/docs/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/docs/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/docs/document-extensions/timeseries/client-api/_overview-csharp.mdx b/docs/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to docs/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/docs/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/javascript-support.mdx b/docs/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/docs/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/docs/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/named-time-series-values.mdx b/docs/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/docs/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/docs/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/docs/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/docs/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/docs/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/docs/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/operations/get.mdx b/docs/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/docs/document-extensions/timeseries/client-api/operations/get.mdx +++ b/docs/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/operations/patch.mdx b/docs/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/docs/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/docs/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/overview.mdx b/docs/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/docs/document-extensions/timeseries/client-api/overview.mdx +++ b/docs/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/append.mdx b/docs/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/docs/document-extensions/timeseries/client-api/session/append.mdx +++ b/docs/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_append-php.mdx b/docs/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_append-php.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_append-python.mdx b/docs/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_append-python.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_delete-php.mdx b/docs/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_delete-python.mdx b/docs/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_patch-php.mdx b/docs/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_patch-python.mdx b/docs/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/delete.mdx b/docs/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/docs/document-extensions/timeseries/client-api/session/delete.mdx +++ b/docs/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/docs/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to docs/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/docs/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/docs/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/docs/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/get/get-names.mdx b/docs/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/docs/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/docs/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/docs/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to docs/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/docs/document-extensions/timeseries/client-api/session/include/overview.mdx b/docs/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/docs/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/docs/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/docs/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/docs/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/docs/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/docs/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/docs/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/docs/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/docs/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/docs/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/docs/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/patch.mdx b/docs/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/docs/document-extensions/timeseries/client-api/session/patch.mdx +++ b/docs/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/client-api/session/querying.mdx b/docs/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/docs/document-extensions/timeseries/client-api/session/querying.mdx +++ b/docs/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/_design-csharp.mdx b/docs/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/_design-csharp.mdx rename to docs/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/docs/document-extensions/timeseries/_design-nodejs.mdx b/docs/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/_design-nodejs.mdx rename to docs/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/docs/document-extensions/timeseries/_indexing-csharp.mdx b/docs/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/_indexing-csharp.mdx rename to docs/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/docs/document-extensions/timeseries/_indexing-nodejs.mdx b/docs/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/_indexing-nodejs.mdx rename to docs/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/docs/document-extensions/timeseries/_indexing-php.mdx b/docs/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/_indexing-php.mdx rename to docs/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/docs/document-extensions/timeseries/_indexing-python.mdx b/docs/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/_indexing-python.mdx rename to docs/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/docs/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/docs/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..c0d3e3b2c5 --- /dev/null +++ b/docs/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,300 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/docs/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/docs/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..57c5f44e40 --- /dev/null +++ b/docs/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,257 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/docs/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/docs/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..7da93ce29a --- /dev/null +++ b/docs/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/docs/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/docs/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..5d3e24fd7f --- /dev/null +++ b/docs/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,309 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/docs/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/docs/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/docs/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/docs/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/docs/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/docs/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/docs/document-extensions/timeseries/design.mdx b/docs/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/docs/document-extensions/timeseries/design.mdx +++ b/docs/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/indexing.mdx b/docs/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/docs/document-extensions/timeseries/indexing.mdx +++ b/docs/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/docs/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 18ae9a014f..0000000000 --- a/docs/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,313 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/docs/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/docs/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index 3c635a3470..0000000000 --- a/docs/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,333 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/docs/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/docs/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index cb160b6ec6..0000000000 --- a/docs/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,282 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/docs/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/docs/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index 2025bccf4a..0000000000 --- a/docs/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/docs/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/docs/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/docs/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/docs/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/choosing-query-range.mdx b/docs/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/docs/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/docs/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/docs/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to docs/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/docs/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to docs/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/docs/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/docs/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to docs/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/docs/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/docs/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to docs/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/docs/document-extensions/timeseries/querying/_filtering-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to docs/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/docs/document-extensions/timeseries/querying/_filtering-php.mdx b/docs/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_filtering-php.mdx rename to docs/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/docs/document-extensions/timeseries/querying/_filtering-python.mdx b/docs/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_filtering-python.mdx rename to docs/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/docs/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_gap-filling-java.mdx b/docs/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to docs/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/docs/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to docs/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..1b0383ae1e --- /dev/null +++ b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,313 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..d4b5203c2b --- /dev/null +++ b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,333 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..76bcc0b26c --- /dev/null +++ b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,282 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..11bb66c408 --- /dev/null +++ b/docs/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/docs/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/docs/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to docs/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/docs/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/docs/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to docs/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/docs/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/docs/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to docs/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/docs/document-extensions/timeseries/querying/_using-indexes-php.mdx b/docs/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to docs/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/docs/document-extensions/timeseries/querying/_using-indexes-python.mdx b/docs/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from docs/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to docs/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/docs/document-extensions/timeseries/querying/filtering.mdx b/docs/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/docs/document-extensions/timeseries/querying/filtering.mdx +++ b/docs/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/gap-filling.mdx b/docs/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/docs/document-extensions/timeseries/querying/gap-filling.mdx +++ b/docs/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/overview-and-syntax.mdx b/docs/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/docs/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/docs/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/querying/stream-timeseries.mdx b/docs/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/docs/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/docs/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/docs/document-extensions/timeseries/querying/using-indexes.mdx b/docs/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/docs/document-extensions/timeseries/querying/using-indexes.mdx +++ b/docs/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/rollup-and-retention.mdx b/docs/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/docs/document-extensions/timeseries/rollup-and-retention.mdx +++ b/docs/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/docs/document-extensions/timeseries/time-series-and-other-features.mdx b/docs/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/docs/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/docs/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/docs/glossary/blittable-json-reader-object.mdx b/docs/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/docs/glossary/blittable-json-reader-object.mdx +++ b/docs/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/docs/glossary/_blittable-json-reader-object-csharp.mdx b/docs/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from docs/glossary/_blittable-json-reader-object-csharp.mdx rename to docs/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/docs/glossary/_copy-attachment-command-data-csharp.mdx b/docs/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_copy-attachment-command-data-csharp.mdx rename to docs/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/docs/glossary/_counters-batch-command-data-csharp.mdx b/docs/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_counters-batch-command-data-csharp.mdx rename to docs/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/docs/glossary/_delete-command-data-csharp.mdx b/docs/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_delete-command-data-csharp.mdx rename to docs/glossary/content/_delete-command-data-csharp.mdx diff --git a/docs/glossary/_index-query-csharp.mdx b/docs/glossary/content/_index-query-csharp.mdx similarity index 100% rename from docs/glossary/_index-query-csharp.mdx rename to docs/glossary/content/_index-query-csharp.mdx diff --git a/docs/glossary/_move-attachment-command-data-csharp.mdx b/docs/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_move-attachment-command-data-csharp.mdx rename to docs/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/docs/glossary/_patch-command-data-csharp.mdx b/docs/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_patch-command-data-csharp.mdx rename to docs/glossary/content/_patch-command-data-csharp.mdx diff --git a/docs/glossary/_put-command-data-csharp.mdx b/docs/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from docs/glossary/_put-command-data-csharp.mdx rename to docs/glossary/content/_put-command-data-csharp.mdx diff --git a/docs/glossary/_query-result-csharp.mdx b/docs/glossary/content/_query-result-csharp.mdx similarity index 100% rename from docs/glossary/_query-result-csharp.mdx rename to docs/glossary/content/_query-result-csharp.mdx diff --git a/docs/glossary/_stream-query-statistics-csharp.mdx b/docs/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from docs/glossary/_stream-query-statistics-csharp.mdx rename to docs/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/docs/glossary/_stream-result-csharp.mdx b/docs/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from docs/glossary/_stream-result-csharp.mdx rename to docs/glossary/content/_stream-result-csharp.mdx diff --git a/docs/glossary/copy-attachment-command-data.mdx b/docs/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/docs/glossary/copy-attachment-command-data.mdx +++ b/docs/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/docs/glossary/counters-batch-command-data.mdx b/docs/glossary/counters-batch-command-data.mdx index d5d5a0082b..7a0db6fcfb 100644 --- a/docs/glossary/counters-batch-command-data.mdx +++ b/docs/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/docs/glossary/delete-command-data.mdx b/docs/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/docs/glossary/delete-command-data.mdx +++ b/docs/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/docs/glossary/index-query.mdx b/docs/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/docs/glossary/index-query.mdx +++ b/docs/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/docs/glossary/move-attachment-command-data.mdx b/docs/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/docs/glossary/move-attachment-command-data.mdx +++ b/docs/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/docs/glossary/patch-command-data.mdx b/docs/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/docs/glossary/patch-command-data.mdx +++ b/docs/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/docs/glossary/put-command-data.mdx b/docs/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/docs/glossary/put-command-data.mdx +++ b/docs/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/docs/glossary/query-result.mdx b/docs/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/docs/glossary/query-result.mdx +++ b/docs/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/docs/glossary/stream-query-statistics.mdx b/docs/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/docs/glossary/stream-query-statistics.mdx +++ b/docs/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/docs/glossary/stream-result.mdx b/docs/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/docs/glossary/stream-result.mdx +++ b/docs/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/docs/indexes/_indexing-hierarchical-data-csharp.mdx b/docs/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/docs/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/docs/indexes/_indexing-hierarchical-data-nodejs.mdx b/docs/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/docs/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/docs/indexes/_indexing-hierarchical-data-php.mdx b/docs/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/docs/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/docs/indexes/_indexing-hierarchical-data-python.mdx b/docs/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/docs/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/docs/indexes/_indexing-nested-data-csharp.mdx b/docs/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/docs/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/docs/indexes/_indexing-nested-data-java.mdx b/docs/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/docs/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/docs/indexes/_indexing-nested-data-nodejs.mdx b/docs/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/docs/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/docs/indexes/_indexing-nested-data-php.mdx b/docs/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/docs/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/docs/indexes/_indexing-nested-data-python.mdx b/docs/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/docs/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/docs/indexes/_indexing-polymorphic-data-csharp.mdx b/docs/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/docs/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/docs/indexes/_indexing-polymorphic-data-java.mdx b/docs/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/docs/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/docs/indexes/_indexing-polymorphic-data-nodejs.mdx b/docs/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/docs/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/docs/indexes/_indexing-polymorphic-data-php.mdx b/docs/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/docs/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/docs/indexes/_indexing-polymorphic-data-python.mdx b/docs/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/docs/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/docs/indexes/_indexing-related-documents-csharp.mdx b/docs/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/docs/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/docs/indexes/_indexing-related-documents-nodejs.mdx b/docs/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/docs/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/docs/indexes/_indexing-related-documents-php.mdx b/docs/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/docs/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/docs/indexes/_indexing-related-documents-python.mdx b/docs/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/docs/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/docs/indexes/_storing-data-in-index-csharp.mdx b/docs/indexes/_storing-data-in-index-csharp.mdx deleted file mode 100644 index d588e9caf4..0000000000 --- a/docs/indexes/_storing-data-in-index-csharp.mdx +++ /dev/null @@ -1,409 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB allows you to store data in a static index. - -* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), - without requiring the server to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - -* In this article: - * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) - * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) - * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) - * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) - - -## What content is stored in the index - -* A static index is defined by its map function which determines the content of each **index-entry**. - Typically, a single index-entry is created for each document from the indexed source collection - - unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. - -* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. - The content of an index-field can be a direct value from the source document field, - or a computed value based on the source document's content. - -* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). - The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. - -* **RavenDB allows you to store the original index-field value in the index**. - **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. - * The tokens (terms) generated by the analyzer are searchable but not stored. - * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) - (by default they are not stored). - -* This behavior is supported by both Lucene and Corax search engines. - - - -## When and why to store data in an index - -* **Store a field in the index if**: - - * **You want to project that field without loading the full document.** - Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. - If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. - * **The index-field is a computed value that you want to return in the query results.** - Normally, querying an index returns matching documents. - But if you're projecting a computed index-field that is Not stored, - you'll need to re-calculate the computed value manually from the documents returned by the query. - Storing the computed field avoids this extra step. - -* **You do not need to store a field in the index in order to**: - - * Filter by the field in a query. - * Perform full-text search on the field. - -* **Disadvantage of storing data in the index**: - - * Increased disk space usage - stored fields take up additional space and increase index size. - - - -## Storing data in index - from the Client API - -To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). -The default is `FieldStorage.No`. -**Index example:** - - - - -{`public class QuantityOrdered_ByCompany : - AbstractIndexCreationTask -{ - // The index-entry: - public class IndexEntry - { - // The index-fields: - public string Company { get; set; } - public string CompanyName { get; set; } - public int TotalItemsOrdered { get; set; } - } - - public QuantityOrdered_ByCompany() - { - Map = orders => from order in orders - select new IndexEntry - { - // 'Company' is a SIMPLE index-field, - // its value is taken directly from the Order document: - Company = order.Company, - - // 'CompanyName' is also considered a simple index-field, - // its value is taken from the related Company document: - CompanyName = LoadDocument(order.Company).Name, - - // 'TotalItemsOrdered' is a COMPUTED index-field: - // (the total quantity of items ordered in an Order document) - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }; - - // Store the calculated 'TotalItemsOrdered' index-field in the index: - // ================================================================== - Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); - - // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: - // ======================================================================================= - Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); - - // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): - // ============================================================================= - Stores.Add(x => x.CompanyName, FieldStorage.Yes); - } -} -`} - - - - -{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask -{ - public QuantityOrdered_ByCompany_JS() - { - Maps = new HashSet() - { - @"map('orders', function(order) { - let company = load(order.Company, 'Companies') - return { - Company: order.Company, - CompanyName: company.Name, - TotalItemsOrdered: order.Lines.reduce(function(total, line) { - return total + line.Quantity; - }, 0) - }; - })" - }; - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - }; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "QuantityOrdered/ByCompany", - - Maps = - { - @"from order in docs.Orders - select new - { - Company = order.Company, - CompanyName = LoadDocument(order.Company, ""Companies"").Name, - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }" - }, - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - } -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -**Querying the index and projecting results:** - - - -* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. - -* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. - The server does Not need to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class NumberOfItemsOrdered -{ - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select TotalItemsOrdered -`} - - - - - - - -* In this query, the projected results are defined by the custom class `ProjectedDetails`. - -* In this case, some of the fields in this class are Not stored in the index, so by default, - the server does need to load the original document from storage to complete the projection. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class ProjectedDetails -{ - // This field was Not stored in the index definition - public string Company { get; set; } - // This field was Not stored in the index definition - public DateTime OrderedAt { get; set; } - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select Company, OrderedAt, TotalItemsOrdered -`} - - - - - - - -## Storing data in index - from the Studio - -To configure index-fields from the Studio, open the _Edit Index_ view: - -![The index](./assets/store-field-in-index-1.png) - -1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). -2. These are the index-fields defined in the index map function. -Scroll down to configure each index-field: - -![Configure index fields](./assets/store-field-in-index-2.png) - -1. Open the _Fields_ tab. -2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. -3. Select _Yes_ from the dropdown to store the field in the index. -4. Here we configure index-field `CompanyName`. -5. This index-field is stored in the index and also configured for full-text search. -When querying the index from the Studio, -you can choose to display the stored index fields in the Results view: - -![Display the stored fields](./assets/store-field-in-index-3.png) - -1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). -2. Open the _Settings_ options. -3. Toggle ON _Show stored index fields only_. -4. When executing the query, - the results will display the stored index-fields for each object returned by the query. - - - - diff --git a/docs/indexes/_using-analyzers-csharp.mdx b/docs/indexes/_using-analyzers-csharp.mdx deleted file mode 100644 index 0c33a1d29f..0000000000 --- a/docs/indexes/_using-analyzers-csharp.mdx +++ /dev/null @@ -1,691 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - - 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - - 2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - use the `Analyzers.Add()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`// The index definition -public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string[] Tags { get; set; } - public string Content { get; set; } - } - - public BlogPosts_ByTagsAndContent() - { - Map = posts => from post in posts - select new IndexEntry() - { - Tags = post.Tags, - Content = post.Content - }; - - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - Analyzers.Add(x => x.Content, - typeof(SnowballAnalyzer).AssemblyQualifiedName); - } -} -`} - - - - -{`// The index definition -var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") -{ - Map = posts => from post in posts - select new {post.Tags, post.Content}, - - Analyzers = - { - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - {x => x.Tags, "SimpleAnalyzer"}, - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} - } -}.ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `FieldIndexing.Exact` - * `FieldIndexing.Search` - * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`public class BlogPosts_ByContent : AbstractIndexCreationTask -\{ - public BlogPosts_ByContent() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Search' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.Search); - - // => Index-field 'Content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `FieldIndexing.Exact`, - RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask -\{ - public Employees_ByFirstAndLastName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName, - FirstName = employee.FirstName - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Exact' on index-field 'FirstName' - Indexes.Add(x => x.FirstName, FieldIndexing.Exact); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstName : AbstractIndexCreationTask -\{ - public Employees_ByFirstName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName - \}; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`public class BlogPosts_ByTitle : AbstractIndexCreationTask -\{ - public BlogPosts_ByTitle() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.No' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.No); - - // Set 'FieldStorage.Yes' to store the original content of field 'Content' - // in the index - Stores.Add(x => x.Content, FieldStorage.Yes); - - // => No analyzer will process field 'Content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public class AnalyzerDefinition -\{ - // Name of the analyzer - public string Name \{ get; set; \} - - // C# source-code of the analyzer - public string Code \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`// Define the put analyzer operation: -var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition -\{ - // The name must be same as the analyzer's class name - Name = "MyAnalyzer", - - Code = @" - using System.IO; - using Lucene.Net.Analysis; - using Lucene.Net.Analysis.Standard; - - namespace MyAnalyzer - \{ - public class MyAnalyzer : Lucene.Net.Analysis.Analyzer - \{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - throw new CodeOmitted(); - \} - \} - \}" -\}); - -// Deploy the analyzer: -store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/docs/indexes/_using-analyzers-nodejs.mdx b/docs/indexes/_using-analyzers-nodejs.mdx deleted file mode 100644 index b120b39ea1..0000000000 --- a/docs/indexes/_using-analyzers-nodejs.mdx +++ /dev/null @@ -1,655 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - -1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - -2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - set the `analyze()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content - })\`; - - // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer - this.analyze("tags", "SimpleAnalyzer"); - - // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer - this.analyze("content", "Raven.Sample.SnowballAnalyzer"); - } -} -`} - - - - -{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); -builder.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content -})\`; -builder.analyzersStrings["tags"] = "SimpleAnalyzer"; -builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; - -await store.maintenance - .send(new PutIndexesOperation( - builder.toIndexDefinition(store.conventions))); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `Exact` - * `Search` - * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Search' on index-field 'content' - this.index("content", "Search"); - - // => Index-field 'content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FirstName = employee.FirstName " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Exact' on index-field 'FirstName' - this.index("FirstName", "Exact"); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName" + - "\})"; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'No' on index-field 'content' - this.index("content", "No"); - - // Set 'Yes' to store the original content of field 'content' in the index - this.store("content", "Yes"); - - // => No analyzer will process field 'content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`const analyzerDefinition = \{ - name: "analyzerName", - code: "code" -\}; -`} - - - -| Parameter | Type | Description | -|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`const analyzerDefinition = \{ - name: "MyAnalyzer", - code: "using System.IO;\\n" + - "using Lucene.Net.Analysis;\\n" + - "using Lucene.Net.Analysis.Standard;\\n" + - "\\n" + - "namespace MyAnalyzer\\n" + - "\{\\n" + - " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + - " \{\\n" + - " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + - " \{\\n" + - " throw new CodeOmitted();\\n" + - " \}\\n" + - " \}\\n" + - "\}\\n" -\}; - -await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/docs/indexes/_using-dynamic-fields-csharp.mdx b/docs/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 30631bba09..0000000000 --- a/docs/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,550 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) diff --git a/docs/indexes/_using-dynamic-fields-java.mdx b/docs/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 2866006674..0000000000 --- a/docs/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,480 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/docs/indexes/_using-dynamic-fields-nodejs.mdx b/docs/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 9bda34e83c..0000000000 --- a/docs/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/docs/indexes/_using-dynamic-fields-php.mdx b/docs/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index d57827b1a7..0000000000 --- a/docs/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,560 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/docs/indexes/_using-dynamic-fields-python.mdx b/docs/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index ffbfebfff6..0000000000 --- a/docs/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,512 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/docs/indexes/_using-term-vectors-csharp.mdx b/docs/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/docs/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/docs/indexes/_what-are-indexes-csharp.mdx b/docs/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index f784c64ebd..0000000000 --- a/docs/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/docs/indexes/_what-are-indexes-java.mdx b/docs/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index bc0dfd5fef..0000000000 --- a/docs/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/docs/indexes/_what-are-indexes-nodejs.mdx b/docs/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/docs/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/docs/indexes/_what-are-indexes-php.mdx b/docs/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/docs/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/docs/indexes/_what-are-indexes-python.mdx b/docs/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/docs/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/docs/indexes/boosting.mdx b/docs/indexes/boosting.mdx index 7afda3c4f5..4384c8e915 100644 --- a/docs/indexes/boosting.mdx +++ b/docs/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/docs/indexes/_boosting-csharp.mdx b/docs/indexes/content/_boosting-csharp.mdx similarity index 100% rename from docs/indexes/_boosting-csharp.mdx rename to docs/indexes/content/_boosting-csharp.mdx diff --git a/docs/indexes/_boosting-java.mdx b/docs/indexes/content/_boosting-java.mdx similarity index 100% rename from docs/indexes/_boosting-java.mdx rename to docs/indexes/content/_boosting-java.mdx diff --git a/docs/indexes/_boosting-nodejs.mdx b/docs/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from docs/indexes/_boosting-nodejs.mdx rename to docs/indexes/content/_boosting-nodejs.mdx diff --git a/docs/indexes/_boosting-php.mdx b/docs/indexes/content/_boosting-php.mdx similarity index 100% rename from docs/indexes/_boosting-php.mdx rename to docs/indexes/content/_boosting-php.mdx diff --git a/docs/indexes/_creating-and-deploying-csharp.mdx b/docs/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from docs/indexes/_creating-and-deploying-csharp.mdx rename to docs/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/docs/indexes/_creating-and-deploying-java.mdx b/docs/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from docs/indexes/_creating-and-deploying-java.mdx rename to docs/indexes/content/_creating-and-deploying-java.mdx diff --git a/docs/indexes/_creating-and-deploying-nodejs.mdx b/docs/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from docs/indexes/_creating-and-deploying-nodejs.mdx rename to docs/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/docs/indexes/_extending-indexes-csharp.mdx b/docs/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_extending-indexes-csharp.mdx rename to docs/indexes/content/_extending-indexes-csharp.mdx diff --git a/docs/indexes/_extending-indexes-java.mdx b/docs/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from docs/indexes/_extending-indexes-java.mdx rename to docs/indexes/content/_extending-indexes-java.mdx diff --git a/docs/indexes/_extending-indexes-nodejs.mdx b/docs/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from docs/indexes/_extending-indexes-nodejs.mdx rename to docs/indexes/content/_extending-indexes-nodejs.mdx diff --git a/docs/indexes/_indexing-basics-csharp.mdx b/docs/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from docs/indexes/_indexing-basics-csharp.mdx rename to docs/indexes/content/_indexing-basics-csharp.mdx diff --git a/docs/indexes/_indexing-basics-java.mdx b/docs/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from docs/indexes/_indexing-basics-java.mdx rename to docs/indexes/content/_indexing-basics-java.mdx diff --git a/docs/indexes/_indexing-basics-nodejs.mdx b/docs/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from docs/indexes/_indexing-basics-nodejs.mdx rename to docs/indexes/content/_indexing-basics-nodejs.mdx diff --git a/docs/indexes/content/_indexing-hierarchical-data-csharp.mdx b/docs/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/docs/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/docs/indexes/_indexing-hierarchical-data-java.mdx b/docs/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from docs/indexes/_indexing-hierarchical-data-java.mdx rename to docs/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/docs/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/docs/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/docs/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/docs/indexes/content/_indexing-hierarchical-data-php.mdx b/docs/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/docs/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/docs/indexes/content/_indexing-hierarchical-data-python.mdx b/docs/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/docs/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/docs/indexes/_indexing-linq-extensions-csharp.mdx b/docs/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from docs/indexes/_indexing-linq-extensions-csharp.mdx rename to docs/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/docs/indexes/_indexing-linq-extensions-java.mdx b/docs/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from docs/indexes/_indexing-linq-extensions-java.mdx rename to docs/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/docs/indexes/_indexing-linq-extensions-nodejs.mdx b/docs/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from docs/indexes/_indexing-linq-extensions-nodejs.mdx rename to docs/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/docs/indexes/_indexing-metadata-csharp.mdx b/docs/indexes/content/_indexing-metadata-csharp.mdx similarity index 100% rename from docs/indexes/_indexing-metadata-csharp.mdx rename to docs/indexes/content/_indexing-metadata-csharp.mdx diff --git a/docs/indexes/_indexing-metadata-java.mdx b/docs/indexes/content/_indexing-metadata-java.mdx similarity index 100% rename from docs/indexes/_indexing-metadata-java.mdx rename to docs/indexes/content/_indexing-metadata-java.mdx diff --git a/docs/indexes/_indexing-metadata-nodejs.mdx b/docs/indexes/content/_indexing-metadata-nodejs.mdx similarity index 100% rename from docs/indexes/_indexing-metadata-nodejs.mdx rename to docs/indexes/content/_indexing-metadata-nodejs.mdx diff --git a/docs/indexes/_indexing-metadata-php.mdx b/docs/indexes/content/_indexing-metadata-php.mdx similarity index 100% rename from docs/indexes/_indexing-metadata-php.mdx rename to docs/indexes/content/_indexing-metadata-php.mdx diff --git a/docs/indexes/_indexing-metadata-python.mdx b/docs/indexes/content/_indexing-metadata-python.mdx similarity index 100% rename from docs/indexes/_indexing-metadata-python.mdx rename to docs/indexes/content/_indexing-metadata-python.mdx diff --git a/docs/indexes/content/_indexing-nested-data-csharp.mdx b/docs/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/docs/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/docs/indexes/content/_indexing-nested-data-java.mdx b/docs/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/docs/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/docs/indexes/content/_indexing-nested-data-nodejs.mdx b/docs/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/docs/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/docs/indexes/content/_indexing-nested-data-php.mdx b/docs/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/docs/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/docs/indexes/content/_indexing-nested-data-python.mdx b/docs/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/docs/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/docs/indexes/content/_indexing-polymorphic-data-csharp.mdx b/docs/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/docs/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/docs/indexes/content/_indexing-polymorphic-data-java.mdx b/docs/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/docs/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/docs/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/docs/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/docs/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/docs/indexes/content/_indexing-polymorphic-data-php.mdx b/docs/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/docs/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/docs/indexes/content/_indexing-polymorphic-data-python.mdx b/docs/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/docs/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/docs/indexes/content/_indexing-related-documents-csharp.mdx b/docs/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/docs/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/docs/indexes/_indexing-related-documents-java.mdx b/docs/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from docs/indexes/_indexing-related-documents-java.mdx rename to docs/indexes/content/_indexing-related-documents-java.mdx diff --git a/docs/indexes/content/_indexing-related-documents-nodejs.mdx b/docs/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/docs/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/docs/indexes/content/_indexing-related-documents-php.mdx b/docs/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/docs/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/docs/indexes/content/_indexing-related-documents-python.mdx b/docs/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/docs/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/docs/indexes/_indexing-spatial-data-csharp.mdx b/docs/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from docs/indexes/_indexing-spatial-data-csharp.mdx rename to docs/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/docs/indexes/_indexing-spatial-data-java.mdx b/docs/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from docs/indexes/_indexing-spatial-data-java.mdx rename to docs/indexes/content/_indexing-spatial-data-java.mdx diff --git a/docs/indexes/_indexing-spatial-data-nodejs.mdx b/docs/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from docs/indexes/_indexing-spatial-data-nodejs.mdx rename to docs/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/docs/indexes/_indexing-spatial-data-php.mdx b/docs/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from docs/indexes/_indexing-spatial-data-php.mdx rename to docs/indexes/content/_indexing-spatial-data-php.mdx diff --git a/docs/indexes/_indexing-spatial-data-python.mdx b/docs/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from docs/indexes/_indexing-spatial-data-python.mdx rename to docs/indexes/content/_indexing-spatial-data-python.mdx diff --git a/docs/indexes/_javascript-indexes-csharp.mdx b/docs/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_javascript-indexes-csharp.mdx rename to docs/indexes/content/_javascript-indexes-csharp.mdx diff --git a/docs/indexes/_javascript-indexes-java.mdx b/docs/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from docs/indexes/_javascript-indexes-java.mdx rename to docs/indexes/content/_javascript-indexes-java.mdx diff --git a/docs/indexes/_map-indexes-csharp.mdx b/docs/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_map-indexes-csharp.mdx rename to docs/indexes/content/_map-indexes-csharp.mdx diff --git a/docs/indexes/_map-indexes-java.mdx b/docs/indexes/content/_map-indexes-java.mdx similarity index 100% rename from docs/indexes/_map-indexes-java.mdx rename to docs/indexes/content/_map-indexes-java.mdx diff --git a/docs/indexes/_map-indexes-nodejs.mdx b/docs/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from docs/indexes/_map-indexes-nodejs.mdx rename to docs/indexes/content/_map-indexes-nodejs.mdx diff --git a/docs/indexes/_map-indexes-php.mdx b/docs/indexes/content/_map-indexes-php.mdx similarity index 100% rename from docs/indexes/_map-indexes-php.mdx rename to docs/indexes/content/_map-indexes-php.mdx diff --git a/docs/indexes/_map-indexes-python.mdx b/docs/indexes/content/_map-indexes-python.mdx similarity index 100% rename from docs/indexes/_map-indexes-python.mdx rename to docs/indexes/content/_map-indexes-python.mdx diff --git a/docs/indexes/_map-reduce-indexes-csharp.mdx b/docs/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_map-reduce-indexes-csharp.mdx rename to docs/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/docs/indexes/_map-reduce-indexes-java.mdx b/docs/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from docs/indexes/_map-reduce-indexes-java.mdx rename to docs/indexes/content/_map-reduce-indexes-java.mdx diff --git a/docs/indexes/_map-reduce-indexes-nodejs.mdx b/docs/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from docs/indexes/_map-reduce-indexes-nodejs.mdx rename to docs/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/docs/indexes/_map-reduce-indexes-php.mdx b/docs/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from docs/indexes/_map-reduce-indexes-php.mdx rename to docs/indexes/content/_map-reduce-indexes-php.mdx diff --git a/docs/indexes/_map-reduce-indexes-python.mdx b/docs/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from docs/indexes/_map-reduce-indexes-python.mdx rename to docs/indexes/content/_map-reduce-indexes-python.mdx diff --git a/docs/indexes/_multi-map-indexes-csharp.mdx b/docs/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_multi-map-indexes-csharp.mdx rename to docs/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/docs/indexes/_multi-map-indexes-java.mdx b/docs/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from docs/indexes/_multi-map-indexes-java.mdx rename to docs/indexes/content/_multi-map-indexes-java.mdx diff --git a/docs/indexes/_multi-map-indexes-nodejs.mdx b/docs/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from docs/indexes/_multi-map-indexes-nodejs.mdx rename to docs/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/docs/indexes/_multi-map-indexes-php.mdx b/docs/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from docs/indexes/_multi-map-indexes-php.mdx rename to docs/indexes/content/_multi-map-indexes-php.mdx diff --git a/docs/indexes/_multi-map-indexes-python.mdx b/docs/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from docs/indexes/_multi-map-indexes-python.mdx rename to docs/indexes/content/_multi-map-indexes-python.mdx diff --git a/docs/indexes/_number-type-conversion-csharp.mdx b/docs/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from docs/indexes/_number-type-conversion-csharp.mdx rename to docs/indexes/content/_number-type-conversion-csharp.mdx diff --git a/docs/indexes/_sorting-and-collation-csharp.mdx b/docs/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from docs/indexes/_sorting-and-collation-csharp.mdx rename to docs/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/docs/indexes/_sorting-and-collation-java.mdx b/docs/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from docs/indexes/_sorting-and-collation-java.mdx rename to docs/indexes/content/_sorting-and-collation-java.mdx diff --git a/docs/indexes/_stale-indexes-csharp.mdx b/docs/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from docs/indexes/_stale-indexes-csharp.mdx rename to docs/indexes/content/_stale-indexes-csharp.mdx diff --git a/docs/indexes/_stale-indexes-java.mdx b/docs/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from docs/indexes/_stale-indexes-java.mdx rename to docs/indexes/content/_stale-indexes-java.mdx diff --git a/docs/indexes/_stale-indexes-nodejs.mdx b/docs/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from docs/indexes/_stale-indexes-nodejs.mdx rename to docs/indexes/content/_stale-indexes-nodejs.mdx diff --git a/docs/indexes/content/_storing-data-in-index-csharp.mdx b/docs/indexes/content/_storing-data-in-index-csharp.mdx new file mode 100644 index 0000000000..08e46be32f --- /dev/null +++ b/docs/indexes/content/_storing-data-in-index-csharp.mdx @@ -0,0 +1,409 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB allows you to store data in a static index. + +* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), + without requiring the server to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + +* In this article: + * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) + * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) + * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) + * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) + + +## What content is stored in the index + +* A static index is defined by its map function which determines the content of each **index-entry**. + Typically, a single index-entry is created for each document from the indexed source collection - + unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. + +* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. + The content of an index-field can be a direct value from the source document field, + or a computed value based on the source document's content. + +* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). + The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. + +* **RavenDB allows you to store the original index-field value in the index**. + **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. + * The tokens (terms) generated by the analyzer are searchable but not stored. + * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) + (by default they are not stored). + +* This behavior is supported by both Lucene and Corax search engines. + + + +## When and why to store data in an index + +* **Store a field in the index if**: + + * **You want to project that field without loading the full document.** + Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. + If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. + * **The index-field is a computed value that you want to return in the query results.** + Normally, querying an index returns matching documents. + But if you're projecting a computed index-field that is Not stored, + you'll need to re-calculate the computed value manually from the documents returned by the query. + Storing the computed field avoids this extra step. + +* **You do not need to store a field in the index in order to**: + + * Filter by the field in a query. + * Perform full-text search on the field. + +* **Disadvantage of storing data in the index**: + + * Increased disk space usage - stored fields take up additional space and increase index size. + + + +## Storing data in index - from the Client API + +To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). +The default is `FieldStorage.No`. +**Index example:** + + + + +{`public class QuantityOrdered_ByCompany : + AbstractIndexCreationTask +{ + // The index-entry: + public class IndexEntry + { + // The index-fields: + public string Company { get; set; } + public string CompanyName { get; set; } + public int TotalItemsOrdered { get; set; } + } + + public QuantityOrdered_ByCompany() + { + Map = orders => from order in orders + select new IndexEntry + { + // 'Company' is a SIMPLE index-field, + // its value is taken directly from the Order document: + Company = order.Company, + + // 'CompanyName' is also considered a simple index-field, + // its value is taken from the related Company document: + CompanyName = LoadDocument(order.Company).Name, + + // 'TotalItemsOrdered' is a COMPUTED index-field: + // (the total quantity of items ordered in an Order document) + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }; + + // Store the calculated 'TotalItemsOrdered' index-field in the index: + // ================================================================== + Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); + + // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: + // ======================================================================================= + Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); + + // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): + // ============================================================================= + Stores.Add(x => x.CompanyName, FieldStorage.Yes); + } +} +`} + + + + +{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask +{ + public QuantityOrdered_ByCompany_JS() + { + Maps = new HashSet() + { + @"map('orders', function(order) { + let company = load(order.Company, 'Companies') + return { + Company: order.Company, + CompanyName: company.Name, + TotalItemsOrdered: order.Lines.reduce(function(total, line) { + return total + line.Quantity; + }, 0) + }; + })" + }; + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + }; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "QuantityOrdered/ByCompany", + + Maps = + { + @"from order in docs.Orders + select new + { + Company = order.Company, + CompanyName = LoadDocument(order.Company, ""Companies"").Name, + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }" + }, + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + } +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +**Querying the index and projecting results:** + + + +* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. + +* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. + The server does Not need to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class NumberOfItemsOrdered +{ + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select TotalItemsOrdered +`} + + + + + + + +* In this query, the projected results are defined by the custom class `ProjectedDetails`. + +* In this case, some of the fields in this class are Not stored in the index, so by default, + the server does need to load the original document from storage to complete the projection. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class ProjectedDetails +{ + // This field was Not stored in the index definition + public string Company { get; set; } + // This field was Not stored in the index definition + public DateTime OrderedAt { get; set; } + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select Company, OrderedAt, TotalItemsOrdered +`} + + + + + + + +## Storing data in index - from the Studio + +To configure index-fields from the Studio, open the _Edit Index_ view: + +![The index](../assets/store-field-in-index-1.png) + +1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). +2. These are the index-fields defined in the index map function. +Scroll down to configure each index-field: + +![Configure index fields](../assets/store-field-in-index-2.png) + +1. Open the _Fields_ tab. +2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. +3. Select _Yes_ from the dropdown to store the field in the index. +4. Here we configure index-field `CompanyName`. +5. This index-field is stored in the index and also configured for full-text search. +When querying the index from the Studio, +you can choose to display the stored index fields in the Results view: + +![Display the stored fields](../assets/store-field-in-index-3.png) + +1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). +2. Open the _Settings_ options. +3. Toggle ON _Show stored index fields only_. +4. When executing the query, + the results will display the stored index-fields for each object returned by the query. + + + + diff --git a/docs/indexes/_storing-data-in-index-java.mdx b/docs/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from docs/indexes/_storing-data-in-index-java.mdx rename to docs/indexes/content/_storing-data-in-index-java.mdx diff --git a/docs/indexes/_storing-data-in-index-nodejs.mdx b/docs/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from docs/indexes/_storing-data-in-index-nodejs.mdx rename to docs/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/docs/indexes/_storing-data-in-index-php.mdx b/docs/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from docs/indexes/_storing-data-in-index-php.mdx rename to docs/indexes/content/_storing-data-in-index-php.mdx diff --git a/docs/indexes/_storing-data-in-index-python.mdx b/docs/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from docs/indexes/_storing-data-in-index-python.mdx rename to docs/indexes/content/_storing-data-in-index-python.mdx diff --git a/docs/indexes/content/_using-analyzers-csharp.mdx b/docs/indexes/content/_using-analyzers-csharp.mdx new file mode 100644 index 0000000000..ee633b3da5 --- /dev/null +++ b/docs/indexes/content/_using-analyzers-csharp.mdx @@ -0,0 +1,691 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + + 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + + 2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + use the `Analyzers.Add()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`// The index definition +public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string[] Tags { get; set; } + public string Content { get; set; } + } + + public BlogPosts_ByTagsAndContent() + { + Map = posts => from post in posts + select new IndexEntry() + { + Tags = post.Tags, + Content = post.Content + }; + + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + Analyzers.Add(x => x.Content, + typeof(SnowballAnalyzer).AssemblyQualifiedName); + } +} +`} + + + + +{`// The index definition +var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") +{ + Map = posts => from post in posts + select new {post.Tags, post.Content}, + + Analyzers = + { + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + {x => x.Tags, "SimpleAnalyzer"}, + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} + } +}.ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `FieldIndexing.Exact` + * `FieldIndexing.Search` + * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`public class BlogPosts_ByContent : AbstractIndexCreationTask +\{ + public BlogPosts_ByContent() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Search' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.Search); + + // => Index-field 'Content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `FieldIndexing.Exact`, + RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask +\{ + public Employees_ByFirstAndLastName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName, + FirstName = employee.FirstName + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Exact' on index-field 'FirstName' + Indexes.Add(x => x.FirstName, FieldIndexing.Exact); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstName : AbstractIndexCreationTask +\{ + public Employees_ByFirstName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName + \}; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`public class BlogPosts_ByTitle : AbstractIndexCreationTask +\{ + public BlogPosts_ByTitle() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.No' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.No); + + // Set 'FieldStorage.Yes' to store the original content of field 'Content' + // in the index + Stores.Add(x => x.Content, FieldStorage.Yes); + + // => No analyzer will process field 'Content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public class AnalyzerDefinition +\{ + // Name of the analyzer + public string Name \{ get; set; \} + + // C# source-code of the analyzer + public string Code \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`// Define the put analyzer operation: +var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition +\{ + // The name must be same as the analyzer's class name + Name = "MyAnalyzer", + + Code = @" + using System.IO; + using Lucene.Net.Analysis; + using Lucene.Net.Analysis.Standard; + + namespace MyAnalyzer + \{ + public class MyAnalyzer : Lucene.Net.Analysis.Analyzer + \{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + throw new CodeOmitted(); + \} + \} + \}" +\}); + +// Deploy the analyzer: +store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/docs/indexes/_using-analyzers-java.mdx b/docs/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from docs/indexes/_using-analyzers-java.mdx rename to docs/indexes/content/_using-analyzers-java.mdx diff --git a/docs/indexes/content/_using-analyzers-nodejs.mdx b/docs/indexes/content/_using-analyzers-nodejs.mdx new file mode 100644 index 0000000000..6d96e400e2 --- /dev/null +++ b/docs/indexes/content/_using-analyzers-nodejs.mdx @@ -0,0 +1,655 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + +1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + +2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + set the `analyze()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content + })\`; + + // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer + this.analyze("tags", "SimpleAnalyzer"); + + // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer + this.analyze("content", "Raven.Sample.SnowballAnalyzer"); + } +} +`} + + + + +{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); +builder.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content +})\`; +builder.analyzersStrings["tags"] = "SimpleAnalyzer"; +builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; + +await store.maintenance + .send(new PutIndexesOperation( + builder.toIndexDefinition(store.conventions))); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `Exact` + * `Search` + * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Search' on index-field 'content' + this.index("content", "Search"); + + // => Index-field 'content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FirstName = employee.FirstName " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Exact' on index-field 'FirstName' + this.index("FirstName", "Exact"); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName" + + "\})"; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'No' on index-field 'content' + this.index("content", "No"); + + // Set 'Yes' to store the original content of field 'content' in the index + this.store("content", "Yes"); + + // => No analyzer will process field 'content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`const analyzerDefinition = \{ + name: "analyzerName", + code: "code" +\}; +`} + + + +| Parameter | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`const analyzerDefinition = \{ + name: "MyAnalyzer", + code: "using System.IO;\\n" + + "using Lucene.Net.Analysis;\\n" + + "using Lucene.Net.Analysis.Standard;\\n" + + "\\n" + + "namespace MyAnalyzer\\n" + + "\{\\n" + + " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + + " \{\\n" + + " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + + " \{\\n" + + " throw new CodeOmitted();\\n" + + " \}\\n" + + " \}\\n" + + "\}\\n" +\}; + +await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/docs/indexes/content/_using-dynamic-fields-csharp.mdx b/docs/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..8484315d55 --- /dev/null +++ b/docs/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,550 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) diff --git a/docs/indexes/content/_using-dynamic-fields-java.mdx b/docs/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..0fd89b32ac --- /dev/null +++ b/docs/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,480 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/docs/indexes/content/_using-dynamic-fields-nodejs.mdx b/docs/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..146a2f25c5 --- /dev/null +++ b/docs/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/docs/indexes/content/_using-dynamic-fields-php.mdx b/docs/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..690dfe4bd2 --- /dev/null +++ b/docs/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,560 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/docs/indexes/content/_using-dynamic-fields-python.mdx b/docs/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..274c90ba20 --- /dev/null +++ b/docs/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,512 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/docs/indexes/content/_using-term-vectors-csharp.mdx b/docs/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/docs/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/docs/indexes/_using-term-vectors-java.mdx b/docs/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from docs/indexes/_using-term-vectors-java.mdx rename to docs/indexes/content/_using-term-vectors-java.mdx diff --git a/docs/indexes/_using-term-vectors-nodejs.mdx b/docs/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from docs/indexes/_using-term-vectors-nodejs.mdx rename to docs/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/docs/indexes/content/_what-are-indexes-csharp.mdx b/docs/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..947039be10 --- /dev/null +++ b/docs/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/docs/indexes/content/_what-are-indexes-java.mdx b/docs/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..8c5adfb5e7 --- /dev/null +++ b/docs/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/docs/indexes/content/_what-are-indexes-nodejs.mdx b/docs/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/docs/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/docs/indexes/content/_what-are-indexes-php.mdx b/docs/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/docs/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/docs/indexes/content/_what-are-indexes-python.mdx b/docs/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/docs/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/docs/indexes/creating-and-deploying.mdx b/docs/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/docs/indexes/creating-and-deploying.mdx +++ b/docs/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/docs/indexes/extending-indexes.mdx b/docs/indexes/extending-indexes.mdx index c8f4e02e47..9336c4eef0 100644 --- a/docs/indexes/extending-indexes.mdx +++ b/docs/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/docs/indexes/indexing-basics.mdx b/docs/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/docs/indexes/indexing-basics.mdx +++ b/docs/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/docs/indexes/indexing-hierarchical-data.mdx b/docs/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/docs/indexes/indexing-hierarchical-data.mdx +++ b/docs/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/docs/indexes/indexing-linq-extensions.mdx b/docs/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/docs/indexes/indexing-linq-extensions.mdx +++ b/docs/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/docs/indexes/indexing-metadata.mdx b/docs/indexes/indexing-metadata.mdx index 0906c90c41..6dad73917f 100644 --- a/docs/indexes/indexing-metadata.mdx +++ b/docs/indexes/indexing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingMetadataCsharp from './_indexing-metadata-csharp.mdx'; -import IndexingMetadataJava from './_indexing-metadata-java.mdx'; -import IndexingMetadataPython from './_indexing-metadata-python.mdx'; -import IndexingMetadataPhp from './_indexing-metadata-php.mdx'; -import IndexingMetadataNodejs from './_indexing-metadata-nodejs.mdx'; +import IndexingMetadataCsharp from './content/_indexing-metadata-csharp.mdx'; +import IndexingMetadataJava from './content/_indexing-metadata-java.mdx'; +import IndexingMetadataPython from './content/_indexing-metadata-python.mdx'; +import IndexingMetadataPhp from './content/_indexing-metadata-php.mdx'; +import IndexingMetadataNodejs from './content/_indexing-metadata-nodejs.mdx'; diff --git a/docs/indexes/indexing-nested-data.mdx b/docs/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/docs/indexes/indexing-nested-data.mdx +++ b/docs/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/docs/indexes/indexing-polymorphic-data.mdx b/docs/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/docs/indexes/indexing-polymorphic-data.mdx +++ b/docs/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/docs/indexes/indexing-related-documents.mdx b/docs/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/docs/indexes/indexing-related-documents.mdx +++ b/docs/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/docs/indexes/indexing-spatial-data.mdx b/docs/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/docs/indexes/indexing-spatial-data.mdx +++ b/docs/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/docs/indexes/javascript-indexes.mdx b/docs/indexes/javascript-indexes.mdx index c3823fd587..d5a516c218 100644 --- a/docs/indexes/javascript-indexes.mdx +++ b/docs/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/docs/indexes/map-indexes.mdx b/docs/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/docs/indexes/map-indexes.mdx +++ b/docs/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/docs/indexes/map-reduce-indexes.mdx b/docs/indexes/map-reduce-indexes.mdx index b783b56532..eb29118146 100644 --- a/docs/indexes/map-reduce-indexes.mdx +++ b/docs/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/docs/indexes/multi-map-indexes.mdx b/docs/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/docs/indexes/multi-map-indexes.mdx +++ b/docs/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/docs/indexes/number-type-conversion.mdx b/docs/indexes/number-type-conversion.mdx index 5e3ee851fc..0640697fce 100644 --- a/docs/indexes/number-type-conversion.mdx +++ b/docs/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/docs/indexes/querying/_faceted-search-csharp.mdx b/docs/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21157296fd..0000000000 --- a/docs/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1052 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/docs/indexes/querying/_faceted-search-java.mdx b/docs/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/docs/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/docs/indexes/querying/_faceted-search-nodejs.mdx b/docs/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/docs/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/docs/indexes/querying/_faceted-search-php.mdx b/docs/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/docs/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/docs/indexes/querying/_faceted-search-python.mdx b/docs/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/docs/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/docs/indexes/querying/_paging-csharp.mdx b/docs/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 7bba94c71c..0000000000 --- a/docs/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,783 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/docs/indexes/querying/_paging-java.mdx b/docs/indexes/querying/_paging-java.mdx deleted file mode 100644 index c69b33f0d7..0000000000 --- a/docs/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,307 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/docs/indexes/querying/_paging-nodejs.mdx b/docs/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 253f2a5e98..0000000000 --- a/docs/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance -**Better performance**: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -**Performance hints**: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/docs/indexes/querying/_paging-php.mdx b/docs/indexes/querying/_paging-php.mdx deleted file mode 100644 index 596a8e12fd..0000000000 --- a/docs/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,688 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/docs/indexes/querying/_paging-python.mdx b/docs/indexes/querying/_paging-python.mdx deleted file mode 100644 index 3ca064b801..0000000000 --- a/docs/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,431 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/docs/indexes/querying/_spatial-java.mdx b/docs/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/docs/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/docs/indexes/querying/_suggestions-csharp.mdx b/docs/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/docs/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/docs/indexes/querying/_suggestions-nodejs.mdx b/docs/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/docs/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/docs/indexes/querying/_suggestions-php.mdx b/docs/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/docs/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/docs/indexes/querying/_suggestions-python.mdx b/docs/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/docs/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/docs/indexes/querying/_distinct-csharp.mdx b/docs/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from docs/indexes/querying/_distinct-csharp.mdx rename to docs/indexes/querying/content/_distinct-csharp.mdx diff --git a/docs/indexes/querying/_distinct-java.mdx b/docs/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from docs/indexes/querying/_distinct-java.mdx rename to docs/indexes/querying/content/_distinct-java.mdx diff --git a/docs/indexes/querying/_distinct-nodejs.mdx b/docs/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_distinct-nodejs.mdx rename to docs/indexes/querying/content/_distinct-nodejs.mdx diff --git a/docs/indexes/querying/_exploration-queries-csharp.mdx b/docs/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from docs/indexes/querying/_exploration-queries-csharp.mdx rename to docs/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/docs/indexes/querying/_exploration-queries-nodejs.mdx b/docs/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_exploration-queries-nodejs.mdx rename to docs/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/docs/indexes/querying/_exploration-queries-php.mdx b/docs/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from docs/indexes/querying/_exploration-queries-php.mdx rename to docs/indexes/querying/content/_exploration-queries-php.mdx diff --git a/docs/indexes/querying/_exploration-queries-python.mdx b/docs/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from docs/indexes/querying/_exploration-queries-python.mdx rename to docs/indexes/querying/content/_exploration-queries-python.mdx diff --git a/docs/indexes/querying/content/_faceted-search-csharp.mdx b/docs/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..7adddea4b9 --- /dev/null +++ b/docs/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1052 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/docs/indexes/querying/content/_faceted-search-java.mdx b/docs/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/docs/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/docs/indexes/querying/content/_faceted-search-nodejs.mdx b/docs/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/docs/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/docs/indexes/querying/content/_faceted-search-php.mdx b/docs/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/docs/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/docs/indexes/querying/content/_faceted-search-python.mdx b/docs/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/docs/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/docs/indexes/querying/_filtering-csharp.mdx b/docs/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from docs/indexes/querying/_filtering-csharp.mdx rename to docs/indexes/querying/content/_filtering-csharp.mdx diff --git a/docs/indexes/querying/_filtering-java.mdx b/docs/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from docs/indexes/querying/_filtering-java.mdx rename to docs/indexes/querying/content/_filtering-java.mdx diff --git a/docs/indexes/querying/_filtering-nodejs.mdx b/docs/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_filtering-nodejs.mdx rename to docs/indexes/querying/content/_filtering-nodejs.mdx diff --git a/docs/indexes/querying/_filtering-php.mdx b/docs/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from docs/indexes/querying/_filtering-php.mdx rename to docs/indexes/querying/content/_filtering-php.mdx diff --git a/docs/indexes/querying/_filtering-python.mdx b/docs/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from docs/indexes/querying/_filtering-python.mdx rename to docs/indexes/querying/content/_filtering-python.mdx diff --git a/docs/indexes/querying/_highlighting-csharp.mdx b/docs/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from docs/indexes/querying/_highlighting-csharp.mdx rename to docs/indexes/querying/content/_highlighting-csharp.mdx diff --git a/docs/indexes/querying/_highlighting-java.mdx b/docs/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from docs/indexes/querying/_highlighting-java.mdx rename to docs/indexes/querying/content/_highlighting-java.mdx diff --git a/docs/indexes/querying/_highlighting-nodejs.mdx b/docs/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_highlighting-nodejs.mdx rename to docs/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/docs/indexes/querying/_highlighting-php.mdx b/docs/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from docs/indexes/querying/_highlighting-php.mdx rename to docs/indexes/querying/content/_highlighting-php.mdx diff --git a/docs/indexes/querying/_highlighting-python.mdx b/docs/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from docs/indexes/querying/_highlighting-python.mdx rename to docs/indexes/querying/content/_highlighting-python.mdx diff --git a/docs/indexes/querying/_include-explanations-csharp.mdx b/docs/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from docs/indexes/querying/_include-explanations-csharp.mdx rename to docs/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/docs/indexes/querying/_include-explanations-nodejs.mdx b/docs/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_include-explanations-nodejs.mdx rename to docs/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/docs/indexes/querying/_intersection-csharp.mdx b/docs/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from docs/indexes/querying/_intersection-csharp.mdx rename to docs/indexes/querying/content/_intersection-csharp.mdx diff --git a/docs/indexes/querying/_intersection-java.mdx b/docs/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from docs/indexes/querying/_intersection-java.mdx rename to docs/indexes/querying/content/_intersection-java.mdx diff --git a/docs/indexes/querying/_intersection-nodejs.mdx b/docs/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_intersection-nodejs.mdx rename to docs/indexes/querying/content/_intersection-nodejs.mdx diff --git a/docs/indexes/querying/_intersection-php.mdx b/docs/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from docs/indexes/querying/_intersection-php.mdx rename to docs/indexes/querying/content/_intersection-php.mdx diff --git a/docs/indexes/querying/_intersection-python.mdx b/docs/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from docs/indexes/querying/_intersection-python.mdx rename to docs/indexes/querying/content/_intersection-python.mdx diff --git a/docs/indexes/querying/_morelikethis-csharp.mdx b/docs/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from docs/indexes/querying/_morelikethis-csharp.mdx rename to docs/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/docs/indexes/querying/_morelikethis-java.mdx b/docs/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from docs/indexes/querying/_morelikethis-java.mdx rename to docs/indexes/querying/content/_morelikethis-java.mdx diff --git a/docs/indexes/querying/_morelikethis-nodejs.mdx b/docs/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_morelikethis-nodejs.mdx rename to docs/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/docs/indexes/querying/_morelikethis-php.mdx b/docs/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from docs/indexes/querying/_morelikethis-php.mdx rename to docs/indexes/querying/content/_morelikethis-php.mdx diff --git a/docs/indexes/querying/_morelikethis-python.mdx b/docs/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from docs/indexes/querying/_morelikethis-python.mdx rename to docs/indexes/querying/content/_morelikethis-python.mdx diff --git a/docs/indexes/querying/content/_paging-csharp.mdx b/docs/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..8f8b1df9c8 --- /dev/null +++ b/docs/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,783 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/docs/indexes/querying/content/_paging-java.mdx b/docs/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..0e9fbc3606 --- /dev/null +++ b/docs/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,307 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/docs/indexes/querying/content/_paging-nodejs.mdx b/docs/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..8f97f74d19 --- /dev/null +++ b/docs/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance +**Better performance**: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +**Performance hints**: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/docs/indexes/querying/content/_paging-php.mdx b/docs/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..9a3a910996 --- /dev/null +++ b/docs/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,688 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/docs/indexes/querying/content/_paging-python.mdx b/docs/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..a357c96094 --- /dev/null +++ b/docs/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,431 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/docs/indexes/querying/_projections-csharp.mdx b/docs/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from docs/indexes/querying/_projections-csharp.mdx rename to docs/indexes/querying/content/_projections-csharp.mdx diff --git a/docs/indexes/querying/_projections-java.mdx b/docs/indexes/querying/content/_projections-java.mdx similarity index 100% rename from docs/indexes/querying/_projections-java.mdx rename to docs/indexes/querying/content/_projections-java.mdx diff --git a/docs/indexes/querying/_projections-nodejs.mdx b/docs/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_projections-nodejs.mdx rename to docs/indexes/querying/content/_projections-nodejs.mdx diff --git a/docs/indexes/querying/_projections-php.mdx b/docs/indexes/querying/content/_projections-php.mdx similarity index 100% rename from docs/indexes/querying/_projections-php.mdx rename to docs/indexes/querying/content/_projections-php.mdx diff --git a/docs/indexes/querying/_projections-python.mdx b/docs/indexes/querying/content/_projections-python.mdx similarity index 100% rename from docs/indexes/querying/_projections-python.mdx rename to docs/indexes/querying/content/_projections-python.mdx diff --git a/docs/indexes/querying/_query-index-csharp.mdx b/docs/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from docs/indexes/querying/_query-index-csharp.mdx rename to docs/indexes/querying/content/_query-index-csharp.mdx diff --git a/docs/indexes/querying/_query-index-java.mdx b/docs/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from docs/indexes/querying/_query-index-java.mdx rename to docs/indexes/querying/content/_query-index-java.mdx diff --git a/docs/indexes/querying/_query-index-nodejs.mdx b/docs/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_query-index-nodejs.mdx rename to docs/indexes/querying/content/_query-index-nodejs.mdx diff --git a/docs/indexes/querying/_query-index-php.mdx b/docs/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from docs/indexes/querying/_query-index-php.mdx rename to docs/indexes/querying/content/_query-index-php.mdx diff --git a/docs/indexes/querying/_query-index-python.mdx b/docs/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from docs/indexes/querying/_query-index-python.mdx rename to docs/indexes/querying/content/_query-index-python.mdx diff --git a/docs/indexes/querying/_searching-csharp.mdx b/docs/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from docs/indexes/querying/_searching-csharp.mdx rename to docs/indexes/querying/content/_searching-csharp.mdx diff --git a/docs/indexes/querying/_searching-java.mdx b/docs/indexes/querying/content/_searching-java.mdx similarity index 100% rename from docs/indexes/querying/_searching-java.mdx rename to docs/indexes/querying/content/_searching-java.mdx diff --git a/docs/indexes/querying/_searching-nodejs.mdx b/docs/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_searching-nodejs.mdx rename to docs/indexes/querying/content/_searching-nodejs.mdx diff --git a/docs/indexes/querying/_searching-php.mdx b/docs/indexes/querying/content/_searching-php.mdx similarity index 100% rename from docs/indexes/querying/_searching-php.mdx rename to docs/indexes/querying/content/_searching-php.mdx diff --git a/docs/indexes/querying/_searching-python.mdx b/docs/indexes/querying/content/_searching-python.mdx similarity index 100% rename from docs/indexes/querying/_searching-python.mdx rename to docs/indexes/querying/content/_searching-python.mdx diff --git a/docs/indexes/querying/_sorting-csharp.mdx b/docs/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from docs/indexes/querying/_sorting-csharp.mdx rename to docs/indexes/querying/content/_sorting-csharp.mdx diff --git a/docs/indexes/querying/_sorting-java.mdx b/docs/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from docs/indexes/querying/_sorting-java.mdx rename to docs/indexes/querying/content/_sorting-java.mdx diff --git a/docs/indexes/querying/_sorting-nodejs.mdx b/docs/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_sorting-nodejs.mdx rename to docs/indexes/querying/content/_sorting-nodejs.mdx diff --git a/docs/indexes/querying/_sorting-php.mdx b/docs/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from docs/indexes/querying/_sorting-php.mdx rename to docs/indexes/querying/content/_sorting-php.mdx diff --git a/docs/indexes/querying/_sorting-python.mdx b/docs/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from docs/indexes/querying/_sorting-python.mdx rename to docs/indexes/querying/content/_sorting-python.mdx diff --git a/docs/indexes/querying/_spatial-csharp.mdx b/docs/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from docs/indexes/querying/_spatial-csharp.mdx rename to docs/indexes/querying/content/_spatial-csharp.mdx diff --git a/docs/indexes/querying/content/_spatial-java.mdx b/docs/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/docs/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/docs/indexes/querying/_spatial-nodejs.mdx b/docs/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from docs/indexes/querying/_spatial-nodejs.mdx rename to docs/indexes/querying/content/_spatial-nodejs.mdx diff --git a/docs/indexes/querying/_spatial-php.mdx b/docs/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from docs/indexes/querying/_spatial-php.mdx rename to docs/indexes/querying/content/_spatial-php.mdx diff --git a/docs/indexes/querying/_spatial-python.mdx b/docs/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from docs/indexes/querying/_spatial-python.mdx rename to docs/indexes/querying/content/_spatial-python.mdx diff --git a/docs/indexes/querying/content/_suggestions-csharp.mdx b/docs/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/docs/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/docs/indexes/querying/_suggestions-java.mdx b/docs/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from docs/indexes/querying/_suggestions-java.mdx rename to docs/indexes/querying/content/_suggestions-java.mdx diff --git a/docs/indexes/querying/content/_suggestions-nodejs.mdx b/docs/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/docs/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/docs/indexes/querying/content/_suggestions-php.mdx b/docs/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/docs/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/docs/indexes/querying/content/_suggestions-python.mdx b/docs/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/docs/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/docs/indexes/querying/_vector-search-csharp.mdx b/docs/indexes/querying/content/_vector-search-csharp.mdx similarity index 100% rename from docs/indexes/querying/_vector-search-csharp.mdx rename to docs/indexes/querying/content/_vector-search-csharp.mdx diff --git a/docs/indexes/querying/distinct.mdx b/docs/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/docs/indexes/querying/distinct.mdx +++ b/docs/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/docs/indexes/querying/exploration-queries.mdx b/docs/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/docs/indexes/querying/exploration-queries.mdx +++ b/docs/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/docs/indexes/querying/faceted-search.mdx b/docs/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/docs/indexes/querying/faceted-search.mdx +++ b/docs/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/docs/indexes/querying/filtering.mdx b/docs/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/docs/indexes/querying/filtering.mdx +++ b/docs/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/docs/indexes/querying/highlighting.mdx b/docs/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/docs/indexes/querying/highlighting.mdx +++ b/docs/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/docs/indexes/querying/include-explanations.mdx b/docs/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/docs/indexes/querying/include-explanations.mdx +++ b/docs/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/docs/indexes/querying/intersection.mdx b/docs/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/docs/indexes/querying/intersection.mdx +++ b/docs/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/docs/indexes/querying/morelikethis.mdx b/docs/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/docs/indexes/querying/morelikethis.mdx +++ b/docs/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/docs/indexes/querying/paging.mdx b/docs/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/docs/indexes/querying/paging.mdx +++ b/docs/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/docs/indexes/querying/projections.mdx b/docs/indexes/querying/projections.mdx index 6a24194fc0..779a07b48b 100644 --- a/docs/indexes/querying/projections.mdx +++ b/docs/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/docs/indexes/querying/query-index.mdx b/docs/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/docs/indexes/querying/query-index.mdx +++ b/docs/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/docs/indexes/querying/searching.mdx b/docs/indexes/querying/searching.mdx index 9f0b5aebc1..9b88c79e82 100644 --- a/docs/indexes/querying/searching.mdx +++ b/docs/indexes/querying/searching.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/docs/indexes/querying/sorting.mdx b/docs/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/docs/indexes/querying/sorting.mdx +++ b/docs/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/docs/indexes/querying/spatial.mdx b/docs/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/docs/indexes/querying/spatial.mdx +++ b/docs/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/docs/indexes/querying/suggestions.mdx b/docs/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/docs/indexes/querying/suggestions.mdx +++ b/docs/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/docs/indexes/querying/vector-search.mdx b/docs/indexes/querying/vector-search.mdx index 696138dc56..2d9834abaa 100644 --- a/docs/indexes/querying/vector-search.mdx +++ b/docs/indexes/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/docs/indexes/sorting-and-collation.mdx b/docs/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/docs/indexes/sorting-and-collation.mdx +++ b/docs/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/docs/indexes/stale-indexes.mdx b/docs/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/docs/indexes/stale-indexes.mdx +++ b/docs/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/docs/indexes/storing-data-in-index.mdx b/docs/indexes/storing-data-in-index.mdx index cb28e5c4f7..e0a7569775 100644 --- a/docs/indexes/storing-data-in-index.mdx +++ b/docs/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "python", "php", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; diff --git a/docs/indexes/using-analyzers.mdx b/docs/indexes/using-analyzers.mdx index bfaac039c9..0993e74dc7 100644 --- a/docs/indexes/using-analyzers.mdx +++ b/docs/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/docs/indexes/using-dynamic-fields.mdx b/docs/indexes/using-dynamic-fields.mdx index d04eae405e..194c98923e 100644 --- a/docs/indexes/using-dynamic-fields.mdx +++ b/docs/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/docs/indexes/using-term-vectors.mdx b/docs/indexes/using-term-vectors.mdx index 48af4fb751..dfbd9448bb 100644 --- a/docs/indexes/using-term-vectors.mdx +++ b/docs/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/docs/indexes/what-are-indexes.mdx b/docs/indexes/what-are-indexes.mdx index b05d8422dc..8821d797d4 100644 --- a/docs/indexes/what-are-indexes.mdx +++ b/docs/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/docs/server/_embedded-csharp.mdx b/docs/server/content/_embedded-csharp.mdx similarity index 100% rename from docs/server/_embedded-csharp.mdx rename to docs/server/content/_embedded-csharp.mdx diff --git a/docs/server/_embedded-java.mdx b/docs/server/content/_embedded-java.mdx similarity index 100% rename from docs/server/_embedded-java.mdx rename to docs/server/content/_embedded-java.mdx diff --git a/docs/server/embedded.mdx b/docs/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/docs/server/embedded.mdx +++ b/docs/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/docs/server/extensions/_refresh-csharp.mdx b/docs/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/docs/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/docs/server/extensions/_expiration-csharp.mdx b/docs/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from docs/server/extensions/_expiration-csharp.mdx rename to docs/server/extensions/content/_expiration-csharp.mdx diff --git a/docs/server/extensions/content/_refresh-csharp.mdx b/docs/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/docs/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/docs/server/extensions/expiration.mdx b/docs/server/extensions/expiration.mdx index 81180dfe2c..3c84777ab1 100644 --- a/docs/server/extensions/expiration.mdx +++ b/docs/server/extensions/expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; diff --git a/docs/server/extensions/refresh.mdx b/docs/server/extensions/refresh.mdx index 9dc2ef60b8..2cd56d007a 100644 --- a/docs/server/extensions/refresh.mdx +++ b/docs/server/extensions/refresh.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; diff --git a/docs/server/kb/_document-identifier-generation-csharp.mdx b/docs/server/kb/content/_document-identifier-generation-csharp.mdx similarity index 100% rename from docs/server/kb/_document-identifier-generation-csharp.mdx rename to docs/server/kb/content/_document-identifier-generation-csharp.mdx diff --git a/docs/server/kb/document-identifier-generation.mdx b/docs/server/kb/document-identifier-generation.mdx index 6bec153835..46a987ed21 100644 --- a/docs/server/kb/document-identifier-generation.mdx +++ b/docs/server/kb/document-identifier-generation.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; +import DocumentIDsCsharp from './content/_document-identifier-generation-csharp.mdx'; diff --git a/docs/server/storage/_documents-compression-csharp.mdx b/docs/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from docs/server/storage/_documents-compression-csharp.mdx rename to docs/server/storage/content/_documents-compression-csharp.mdx diff --git a/docs/server/storage/_documents-compression-nodejs.mdx b/docs/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from docs/server/storage/_documents-compression-nodejs.mdx rename to docs/server/storage/content/_documents-compression-nodejs.mdx diff --git a/docs/server/storage/documents-compression.mdx b/docs/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/docs/server/storage/documents-compression.mdx +++ b/docs/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/docs/start/_test-driver-csharp.mdx b/docs/start/content/_test-driver-csharp.mdx similarity index 100% rename from docs/start/_test-driver-csharp.mdx rename to docs/start/content/_test-driver-csharp.mdx diff --git a/docs/start/_test-driver-java.mdx b/docs/start/content/_test-driver-java.mdx similarity index 100% rename from docs/start/_test-driver-java.mdx rename to docs/start/content/_test-driver-java.mdx diff --git a/docs/start/guides/azure-functions/_existing-project-csharp.mdx b/docs/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/docs/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/docs/start/guides/azure-functions/_existing-project-nodejs.mdx b/docs/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/docs/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/docs/start/guides/azure-functions/_overview-csharp.mdx b/docs/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/docs/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/docs/start/guides/azure-functions/_overview-nodejs.mdx b/docs/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index e9abea53ff..0000000000 --- a/docs/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/docs/start/guides/azure-functions/content/_existing-project-csharp.mdx b/docs/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/docs/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/docs/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/docs/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/docs/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/docs/start/guides/azure-functions/content/_overview-csharp.mdx b/docs/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/docs/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/docs/start/guides/azure-functions/content/_overview-nodejs.mdx b/docs/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..a6bf58b4c8 --- /dev/null +++ b/docs/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/docs/start/guides/azure-functions/existing-project.mdx b/docs/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/docs/start/guides/azure-functions/existing-project.mdx +++ b/docs/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/docs/start/guides/azure-functions/overview.mdx b/docs/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/docs/start/guides/azure-functions/overview.mdx +++ b/docs/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/docs/start/test-driver.mdx b/docs/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/docs/start/test-driver.mdx +++ b/docs/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-3.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-3.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-3.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-3.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-3.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-3.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 0a7e64adb2..cc27d6a420 100644 --- a/versioned_docs/version-3.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-3.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx b/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx deleted file mode 100644 index 40c877329e..0000000000 --- a/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx +++ /dev/null @@ -1,228 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. - -## **Failover behavior** - - By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: - -* Detecting that an instance is replicating to another set of instances. -* When that instance is down, the client will be automatically shifted to other instances. - -This is caused by a failover mechanism which is turned in a document stored by default. The client can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. - - -The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. - - -You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option - - - -{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; -`} - - - -When `FailImmediately` option is used then client will raise exception when primary server is down. - -The remaining values of `FailoverBehavior` enumeration are: - -* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) -* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) -* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master - -They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. - - - -FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: - - - -{`store.Conventions.FailoverBehavior = FailoverBehavior.ReadFromAllServers - | FailoverBehavior.AllowReadsFromSecondariesAndWritesToSecondaries; -`} - - - - - - - -## **Discovering destinations** - -Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. - -Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. - - - -## **Failover servers** - - -If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. - - -### Setup - - - -{`store.FailoverServers = new FailoverServers(); -store.FailoverServers.ForDefaultDatabase = new[] -\{ - new ReplicationDestination - \{ - Url = "http://localhost:8078", - ApiKey = "apikey" - \}, - new ReplicationDestination - \{ - Url = "http://localhost:8077/", - Database = "test", - Username = "user", - Password = "secret" - \} -\}; - -store.FailoverServers.ForDatabases = new Dictionary -\{ - \{ - "Northwind", - new[] - \{ - new ReplicationDestination - \{ - Url = "http://localhost:8076" - \} - \} - \} -\}; -`} - - - -### Setup using connection string - -To setup a failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use the `Failover` option. Multiple failovers can be setup using multiple `Failover` options. - -Failover -: Type: string in predefined format -: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` -Failover server definition. - -Example: - - - -{`session.Store(new ReplicationDocument -\{ - ClientConfiguration = new ReplicationClientConfiguration - \{ - FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader - \} - -\}, "Raven/Replication/Destinations"); -`} - - - -Full example: - - - -{` - - -`} - - - - - -## **Setting up default client configuration on server** - -Default client configuration can be 'injected' into a client, by filling out the `ClientConfiguration` property in `Raven/Replication/Destinations`. - -The available options are: - -- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. - -Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. - -![Setting up default client configuration on server](./assets/replication-client-configuration.png) - - - -## **Request redirection** - -The Raven Client API is quite intelligent in this regard, as upon failure it will: - -* Assume that the failure is transient, and retry the request, -* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, -* After ten consecutive failures, Raven will start replicating to this node less often - * Once every 10 requests, until failure count reaches 100 - * Once every 100 requests, until failure count reaches 1,000 - * Once every 1,000 requests, when failure count is above 1,000 -* On the first successful request, the failure count is reset. - -If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. - - - -## **Back to primary** - -The client shifted to a replicated node will go back to its primary server -as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. - - - -## **Replicated operations** - -At a lower level, the following operations support replication: - -* Get - single document and multi documents -* Put -* Delete -* Query -* Rollback -* Commit - -The following operations do not support replication in the Client API: - -* PutIndex -* DeleteIndex - - - -## **Custom document ID generation** - -The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids). -However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect -against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: - - - -{`store - .DatabaseCommands - .Put( -verPrefixForHilo", - null, -Object - \{ -rPrefix", "NorthServer/" \} - \}, -Object()); -`} - - - -The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. -For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. - - - - diff --git a/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx b/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx deleted file mode 100644 index ecc950ab75..0000000000 --- a/versioned_docs/version-3.0/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx +++ /dev/null @@ -1,207 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. - -## **Failover behavior** - - By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: - -* Detecting that an instance is replicating to another set of instances. -* When that instance is down, the client will be automatically shifted to other instances. - -This is caused by a failover mechanism which is turned in a document stored by default. The clinet can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. - - -The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. - - -You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option: - - - -{`store.getConventions().setFailoverBehavior(FailoverBehaviorSet.of(FailoverBehavior.FAIL_IMMEDIATELY)); -`} - - - -When `FailImmediately` option is used then client will raise exception when primary server is down. - -The remaining values of `FailoverBehavior` enumeration are: - -* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) -* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) -* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master - -They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. - - - -FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: - - - -{`store.getConventions().setFailoverBehavior( - FailoverBehaviorSet.of( - FailoverBehavior.READ_FROM_ALL_SERVERS, - FailoverBehavior.ALLOW_READS_FROM_SECONDARIES_AND_WRITES_TO_SECONDARIES)); -`} - - - - - - - -## **Discovering destinations** - -Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. - -Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. - - - -## **Failover servers** - -If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. - -### Setup - - - -{`store.setFailoverServers(new FailoverServers()); -ReplicationDestination destination1 = new ReplicationDestination(); -destination1.setUrl("http://localhost:8078"); -destination1.setApiKey("apikey"); - -ReplicationDestination destination2 = new ReplicationDestination(); -destination2.setUrl("http://localhost:8077"); -destination2.setDatabase("test"); -destination2.setUsername("user"); -destination2.setPassword("secret"); -store.getFailoverServers().addForDefaultDatabase(destination1, destination2); - -ReplicationDestination northwindDestination = new ReplicationDestination(); -northwindDestination.setUrl("http://localhost:8076"); - -store.getFailoverServers().addForDatabase("Northwind", northwindDestination); -`} - - - -### Setup using connection string - -To setup failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use `Failover` option. Multiple failovers can be setup using multiple `Failover` options. - -Failover -: Type: string in predefined format -: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` -Failover server definition. - -Example: - - - -{`Url = http://localhost:59233; - // Primary server url -Failover = \{ Url:'http://localhost:8078'\}; - // Failover for DefaultDatabase -Failover = \{ Url:'http://localhost:8077/', Database:'test'\}; - // Failover for DefaultDatabase with non-default database -Failover = Northwind|\{ Url:'http://localhost:8076/'\}; - // Failover for 'Northwind' database -Failover= \{ Url:'http://localhost:8075', Username:'user', Password:'secret'\}; - // Failover for DefaultDatabase with Username and Password -Failover= \{ Url:'http://localhost:8074', ApiKey:'d5723e19-92ad-4531-adad-8611e6e05c8a'\} - // Failover for DefaultDatabase with ApiKey -`} - - - - - -## **Setting up default client configuration on server** - -Default client configuration can be 'injected' into client, by filling out `ClientConfiguration` property in `Raven/Replication/Destinations`. - -The available options are: - -- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. - -Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. - -![Setting up default client configuration on server](./assets/replication-client-configuration.png) - - - -## **Request redirection** - -The Raven Client API is quite intelligent in this regard, as upon failure it will: - -* Assume that the failure is transient, and retry the request, -* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, -* After ten consecutive failures, Raven will start replicating to this node less often - * Once every 10 requests, until failure count reaches 100 - * Once every 100 requests, until failure count reaches 1,000 - * Once every 1,000 requests, when failure count is above 1,000 -* On the first successful request, the failure count is reset. - -If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. - - - -## **Back to primary** - -The client shifted to a replicated node will go back to its primary server -as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. - - - -## **Replicated operations** - -At a lower level, the following operations support replication: - -* Get - single document and multi documents -* Put -* Delete -* Query -* Rollback -* Commit - -The following operations do not support replication in the Client API: - -* PutIndex -* DeleteIndex - - - -## **Custom document ID generation** - -The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids) -However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect -against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: - - - -{`store - .DatabaseCommands - .Put( -verPrefixForHilo", - null, -Object - \{ -rPrefix", "NorthServer/" \} - \}, -Object()); -`} - - - -The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. -For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. - - - - diff --git a/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx b/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx new file mode 100644 index 0000000000..464320db12 --- /dev/null +++ b/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx @@ -0,0 +1,228 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. + +## **Failover behavior** + + By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: + +* Detecting that an instance is replicating to another set of instances. +* When that instance is down, the client will be automatically shifted to other instances. + +This is caused by a failover mechanism which is turned in a document stored by default. The client can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. + + +The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. + + +You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option + + + +{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; +`} + + + +When `FailImmediately` option is used then client will raise exception when primary server is down. + +The remaining values of `FailoverBehavior` enumeration are: + +* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) +* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) +* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master + +They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. + + + +FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: + + + +{`store.Conventions.FailoverBehavior = FailoverBehavior.ReadFromAllServers + | FailoverBehavior.AllowReadsFromSecondariesAndWritesToSecondaries; +`} + + + + + + + +## **Discovering destinations** + +Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. + +Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. + + + +## **Failover servers** + + +If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. + + +### Setup + + + +{`store.FailoverServers = new FailoverServers(); +store.FailoverServers.ForDefaultDatabase = new[] +\{ + new ReplicationDestination + \{ + Url = "http://localhost:8078", + ApiKey = "apikey" + \}, + new ReplicationDestination + \{ + Url = "http://localhost:8077/", + Database = "test", + Username = "user", + Password = "secret" + \} +\}; + +store.FailoverServers.ForDatabases = new Dictionary +\{ + \{ + "Northwind", + new[] + \{ + new ReplicationDestination + \{ + Url = "http://localhost:8076" + \} + \} + \} +\}; +`} + + + +### Setup using connection string + +To setup a failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use the `Failover` option. Multiple failovers can be setup using multiple `Failover` options. + +Failover +: Type: string in predefined format +: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` +Failover server definition. + +Example: + + + +{`session.Store(new ReplicationDocument +\{ + ClientConfiguration = new ReplicationClientConfiguration + \{ + FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader + \} + +\}, "Raven/Replication/Destinations"); +`} + + + +Full example: + + + +{` + + +`} + + + + + +## **Setting up default client configuration on server** + +Default client configuration can be 'injected' into a client, by filling out the `ClientConfiguration` property in `Raven/Replication/Destinations`. + +The available options are: + +- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. + +Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. + +![Setting up default client configuration on server](../assets/replication-client-configuration.png) + + + +## **Request redirection** + +The Raven Client API is quite intelligent in this regard, as upon failure it will: + +* Assume that the failure is transient, and retry the request, +* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, +* After ten consecutive failures, Raven will start replicating to this node less often + * Once every 10 requests, until failure count reaches 100 + * Once every 100 requests, until failure count reaches 1,000 + * Once every 1,000 requests, when failure count is above 1,000 +* On the first successful request, the failure count is reset. + +If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. + + + +## **Back to primary** + +The client shifted to a replicated node will go back to its primary server +as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. + + + +## **Replicated operations** + +At a lower level, the following operations support replication: + +* Get - single document and multi documents +* Put +* Delete +* Query +* Rollback +* Commit + +The following operations do not support replication in the Client API: + +* PutIndex +* DeleteIndex + + + +## **Custom document ID generation** + +The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids). +However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect +against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: + + + +{`store + .DatabaseCommands + .Put( +verPrefixForHilo", + null, +Object + \{ +rPrefix", "NorthServer/" \} + \}, +Object()); +`} + + + +The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. +For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. + + + + diff --git a/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx b/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx new file mode 100644 index 0000000000..3503161bd2 --- /dev/null +++ b/versioned_docs/version-3.0/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx @@ -0,0 +1,207 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. + +## **Failover behavior** + + By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: + +* Detecting that an instance is replicating to another set of instances. +* When that instance is down, the client will be automatically shifted to other instances. + +This is caused by a failover mechanism which is turned in a document stored by default. The clinet can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. + + +The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. + + +You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option: + + + +{`store.getConventions().setFailoverBehavior(FailoverBehaviorSet.of(FailoverBehavior.FAIL_IMMEDIATELY)); +`} + + + +When `FailImmediately` option is used then client will raise exception when primary server is down. + +The remaining values of `FailoverBehavior` enumeration are: + +* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) +* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) +* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master + +They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. + + + +FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: + + + +{`store.getConventions().setFailoverBehavior( + FailoverBehaviorSet.of( + FailoverBehavior.READ_FROM_ALL_SERVERS, + FailoverBehavior.ALLOW_READS_FROM_SECONDARIES_AND_WRITES_TO_SECONDARIES)); +`} + + + + + + + +## **Discovering destinations** + +Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. + +Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. + + + +## **Failover servers** + +If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. + +### Setup + + + +{`store.setFailoverServers(new FailoverServers()); +ReplicationDestination destination1 = new ReplicationDestination(); +destination1.setUrl("http://localhost:8078"); +destination1.setApiKey("apikey"); + +ReplicationDestination destination2 = new ReplicationDestination(); +destination2.setUrl("http://localhost:8077"); +destination2.setDatabase("test"); +destination2.setUsername("user"); +destination2.setPassword("secret"); +store.getFailoverServers().addForDefaultDatabase(destination1, destination2); + +ReplicationDestination northwindDestination = new ReplicationDestination(); +northwindDestination.setUrl("http://localhost:8076"); + +store.getFailoverServers().addForDatabase("Northwind", northwindDestination); +`} + + + +### Setup using connection string + +To setup failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use `Failover` option. Multiple failovers can be setup using multiple `Failover` options. + +Failover +: Type: string in predefined format +: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` +Failover server definition. + +Example: + + + +{`Url = http://localhost:59233; + // Primary server url +Failover = \{ Url:'http://localhost:8078'\}; + // Failover for DefaultDatabase +Failover = \{ Url:'http://localhost:8077/', Database:'test'\}; + // Failover for DefaultDatabase with non-default database +Failover = Northwind|\{ Url:'http://localhost:8076/'\}; + // Failover for 'Northwind' database +Failover= \{ Url:'http://localhost:8075', Username:'user', Password:'secret'\}; + // Failover for DefaultDatabase with Username and Password +Failover= \{ Url:'http://localhost:8074', ApiKey:'d5723e19-92ad-4531-adad-8611e6e05c8a'\} + // Failover for DefaultDatabase with ApiKey +`} + + + + + +## **Setting up default client configuration on server** + +Default client configuration can be 'injected' into client, by filling out `ClientConfiguration` property in `Raven/Replication/Destinations`. + +The available options are: + +- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. + +Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. + +![Setting up default client configuration on server](../assets/replication-client-configuration.png) + + + +## **Request redirection** + +The Raven Client API is quite intelligent in this regard, as upon failure it will: + +* Assume that the failure is transient, and retry the request, +* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, +* After ten consecutive failures, Raven will start replicating to this node less often + * Once every 10 requests, until failure count reaches 100 + * Once every 100 requests, until failure count reaches 1,000 + * Once every 1,000 requests, when failure count is above 1,000 +* On the first successful request, the failure count is reset. + +If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. + + + +## **Back to primary** + +The client shifted to a replicated node will go back to its primary server +as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. + + + +## **Replicated operations** + +At a lower level, the following operations support replication: + +* Get - single document and multi documents +* Put +* Delete +* Query +* Rollback +* Commit + +The following operations do not support replication in the Client API: + +* PutIndex +* DeleteIndex + + + +## **Custom document ID generation** + +The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids) +However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect +against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: + + + +{`store + .DatabaseCommands + .Put( +verPrefixForHilo", + null, +Object + \{ +rPrefix", "NorthServer/" \} + \}, +Object()); +`} + + + +The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. +For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. + + + + diff --git a/versioned_docs/version-3.0/client-api/bundles/how-client-integrates-with-replication-bundle.mdx b/versioned_docs/version-3.0/client-api/bundles/how-client-integrates-with-replication-bundle.mdx index fc5f2a1099..38976c8939 100644 --- a/versioned_docs/version-3.0/client-api/bundles/how-client-integrates-with-replication-bundle.mdx +++ b/versioned_docs/version-3.0/client-api/bundles/how-client-integrates-with-replication-bundle.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationBundleCsharp from './_how-client-integrates-with-replication-bundle-csharp.mdx'; -import HowClientIntegratesWithReplicationBundleJava from './_how-client-integrates-with-replication-bundle-java.mdx'; +import HowClientIntegratesWithReplicationBundleCsharp from './content/_how-client-integrates-with-replication-bundle-csharp.mdx'; +import HowClientIntegratesWithReplicationBundleJava from './content/_how-client-integrates-with-replication-bundle-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-data-subscription-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-data-subscription-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-data-subscription-changes-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-data-subscription-changes-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-replication-conflicts-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-replication-conflicts-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-replication-conflicts-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-replication-conflicts-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-transformer-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-transformer-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-transformer-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-transformer-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-transformer-changes-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-transformer-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_how-to-subscribe-to-transformer-changes-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_how-to-subscribe-to-transformer-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-3.0/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-3.0/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-3.0/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx index 5f30dac431..a9e1a1739f 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToBulkInsertOperationChangesCsharp from './_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx'; -import HowToSubscribeToBulkInsertOperationChangesJava from './_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx'; +import HowToSubscribeToBulkInsertOperationChangesCsharp from './content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx'; +import HowToSubscribeToBulkInsertOperationChangesJava from './content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx index 11b8626913..6a9ad5e005 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDataSubscriptionChangesCsharp from './_how-to-subscribe-to-data-subscription-changes-csharp.mdx'; -import HowToSubscribeToDataSubscriptionChangesJava from './_how-to-subscribe-to-data-subscription-changes-java.mdx'; +import HowToSubscribeToDataSubscriptionChangesCsharp from './content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx'; +import HowToSubscribeToDataSubscriptionChangesJava from './content/_how-to-subscribe-to-data-subscription-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-document-changes.mdx index 84fcfd9ba3..2328b288d4 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-index-changes.mdx index fe745027fa..35c0d1ac48 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx index c3fc5f89b3..37fc5297ae 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToReplicationConflictsCsharp from './_how-to-subscribe-to-replication-conflicts-csharp.mdx'; -import HowToSubscribeToReplicationConflictsJava from './_how-to-subscribe-to-replication-conflicts-java.mdx'; +import HowToSubscribeToReplicationConflictsCsharp from './content/_how-to-subscribe-to-replication-conflicts-csharp.mdx'; +import HowToSubscribeToReplicationConflictsJava from './content/_how-to-subscribe-to-replication-conflicts-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-transformer-changes.mdx b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-transformer-changes.mdx index f69a415b0c..a0fefb0ece 100644 --- a/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-transformer-changes.mdx +++ b/versioned_docs/version-3.0/client-api/changes/how-to-subscribe-to-transformer-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTransformerChangesCsharp from './_how-to-subscribe-to-transformer-changes-csharp.mdx'; -import HowToSubscribeToTransformerChangesJava from './_how-to-subscribe-to-transformer-changes-java.mdx'; +import HowToSubscribeToTransformerChangesCsharp from './content/_how-to-subscribe-to-transformer-changes-csharp.mdx'; +import HowToSubscribeToTransformerChangesJava from './content/_how-to-subscribe-to-transformer-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-3.0/client-api/changes/what-is-changes-api.mdx index f1d76c7ebe..8b17716eca 100644 --- a/versioned_docs/version-3.0/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-3.0/client-api/changes/what-is-changes-api.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_delete-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_delete-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_delete-http.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_delete-http.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_delete-java.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_delete-java.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_delete-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_get-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_get-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_get-http.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_get-http.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_get-java.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_get-java.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_get-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_put-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_put-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_put-http.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_put-http.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_put-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/_put-java.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/_put-java.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/content/_put-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/delete.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/delete.mdx index 255c00d87f..0eafa31139 100644 --- a/versioned_docs/version-3.0/client-api/commands/attachments/delete.mdx +++ b/versioned_docs/version-3.0/client-api/commands/attachments/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/get.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/get.mdx index 003c60c1b0..f203a36f83 100644 --- a/versioned_docs/version-3.0/client-api/commands/attachments/get.mdx +++ b/versioned_docs/version-3.0/client-api/commands/attachments/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-http.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-http.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-java.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_get-attachment-metadata-only-java.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-http.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-http.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-java.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/attachments/how-to/_update-attachment-metadata-only-java.mdx rename to versioned_docs/version-3.0/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx index fb86765737..0838e34e22 100644 --- a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx +++ b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentMetadataOnlyCsharp from './_get-attachment-metadata-only-csharp.mdx'; -import GetAttachmentMetadataOnlyJava from './_get-attachment-metadata-only-java.mdx'; -import GetAttachmentMetadataOnlyHttp from './_get-attachment-metadata-only-http.mdx'; +import GetAttachmentMetadataOnlyCsharp from './content/_get-attachment-metadata-only-csharp.mdx'; +import GetAttachmentMetadataOnlyJava from './content/_get-attachment-metadata-only-java.mdx'; +import GetAttachmentMetadataOnlyHttp from './content/_get-attachment-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx index 48c9347300..75316722e2 100644 --- a/versioned_docs/version-3.0/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx +++ b/versioned_docs/version-3.0/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateAttachmentMetadataOnlyCsharp from './_update-attachment-metadata-only-csharp.mdx'; -import UpdateAttachmentMetadataOnlyJava from './_update-attachment-metadata-only-java.mdx'; -import UpdateAttachmentMetadataOnlyHttp from './_update-attachment-metadata-only-http.mdx'; +import UpdateAttachmentMetadataOnlyCsharp from './content/_update-attachment-metadata-only-csharp.mdx'; +import UpdateAttachmentMetadataOnlyJava from './content/_update-attachment-metadata-only-java.mdx'; +import UpdateAttachmentMetadataOnlyHttp from './content/_update-attachment-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/attachments/put.mdx b/versioned_docs/version-3.0/client-api/commands/attachments/put.mdx index 5d5e964e73..1ee613c8b5 100644 --- a/versioned_docs/version-3.0/client-api/commands/attachments/put.mdx +++ b/versioned_docs/version-3.0/client-api/commands/attachments/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-http.mdx b/versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-http.mdx rename to versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-3.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-3.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 649fbdc2b1..d61bf602a6 100644 --- a/versioned_docs/version-3.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-3.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchHttp from './_how-to-send-multiple-commands-using-a-batch-http.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchHttp from './content/_how-to-send-multiple-commands-using-a-batch-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/_what-are-commands-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/_what-are-commands-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/_what-are-commands-http.mdx b/versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/_what-are-commands-http.mdx rename to versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/_what-are-commands-java.mdx b/versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/_what-are-commands-java.mdx rename to versioned_docs/version-3.0/client-api/commands/content/_what-are-commands-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_delete-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_delete-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_delete-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_get-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_get-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_put-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_put-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_put-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_stream-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_stream-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_stream-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_stream-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_stream-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_stream-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_stream-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_stream-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/_stream-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/content/_stream-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/_stream-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/content/_stream-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/delete.mdx b/versioned_docs/version-3.0/client-api/commands/documents/delete.mdx index f8ed6a316e..48a372e500 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/documents/get.mdx b/versioned_docs/version-3.0/client-api/commands/documents/get.mdx index 746765561b..a9f16c255b 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-http.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-http.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-3.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx index 0ef6a80beb..3e7a49cdde 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteOrUpdateDocumentsUsingIndexCsharp from './_delete-or-update-documents-using-index-csharp.mdx'; -import DeleteOrUpdateDocumentsUsingIndexJava from './_delete-or-update-documents-using-index-java.mdx'; -import DeleteOrUpdateDocumentsUsingIndexHttp from './_delete-or-update-documents-using-index-http.mdx'; +import DeleteOrUpdateDocumentsUsingIndexCsharp from './content/_delete-or-update-documents-using-index-csharp.mdx'; +import DeleteOrUpdateDocumentsUsingIndexJava from './content/_delete-or-update-documents-using-index-java.mdx'; +import DeleteOrUpdateDocumentsUsingIndexHttp from './content/_delete-or-update-documents-using-index-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-3.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx index b96a821d1f..84c29e6a54 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; -import GetDocumentMetadataOnlyHttp from './_get-document-metadata-only-http.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyHttp from './content/_get-document-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/documents/put.mdx b/versioned_docs/version-3.0/client-api/commands/documents/put.mdx index d9abd08bfd..a295f0a5f8 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/documents/stream.mdx b/versioned_docs/version-3.0/client-api/commands/documents/stream.mdx index 8c0083dbef..3571040d36 100644 --- a/versioned_docs/version-3.0/client-api/commands/documents/stream.mdx +++ b/versioned_docs/version-3.0/client-api/commands/documents/stream.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamCsharp from './_stream-csharp.mdx'; -import StreamJava from './_stream-java.mdx'; -import StreamHttp from './_stream-http.mdx'; +import StreamCsharp from './content/_stream-csharp.mdx'; +import StreamJava from './content/_stream-java.mdx'; +import StreamHttp from './content/_stream-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/compact-database.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/compact-database.mdx index aa76721e79..3f7f8d2890 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/compact-database.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/compact-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseJava from './_compact-database-java.mdx'; -import CompactDatabaseHttp from './_compact-database-http.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseJava from './content/_compact-database-java.mdx'; +import CompactDatabaseHttp from './content/_compact-database-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_compact-database-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_compact-database-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_create-delete-database-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_create-delete-database-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_disable-caching-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_disable-caching-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_disable-caching-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_disable-caching-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_disable-caching-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_disable-caching-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-and-server-statistics-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-and-server-statistics-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-database-configuration-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-database-configuration-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-full-url-for-a-document-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-full-url-for-a-document-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-full-url-for-a-document-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-full-url-for-a-document-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-full-url-for-a-document-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-full-url-for-a-document-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-full-url-for-a-document-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-full-url-for-a-document-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_get-server-build-number-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_get-server-build-number-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-backup-restore-operations-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-backup-restore-operations-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-reducing-http.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-reducing-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_start-stop-reducing-http.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_start-stop-reducing-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-credentials-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-credentials-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-credentials-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-credentials-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-credentials-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-credentials-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-credentials-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-credentials-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-to-a-different-database-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-to-a-different-database-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-to-a-different-database-java.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/how-to/_switch-commands-to-a-different-database-java.mdx rename to versioned_docs/version-3.0/client-api/commands/how-to/content/_switch-commands-to-a-different-database-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/create-delete-database.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/create-delete-database.mdx index d8df725f6d..c2fd7786aa 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/create-delete-database.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/create-delete-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDeleteDatabaseCsharp from './_create-delete-database-csharp.mdx'; -import CreateDeleteDatabaseJava from './_create-delete-database-java.mdx'; -import CreateDeleteDatabaseHttp from './_create-delete-database-http.mdx'; +import CreateDeleteDatabaseCsharp from './content/_create-delete-database-csharp.mdx'; +import CreateDeleteDatabaseJava from './content/_create-delete-database-java.mdx'; +import CreateDeleteDatabaseHttp from './content/_create-delete-database-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/disable-caching.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/disable-caching.mdx index 3e8d448875..2751aa36e0 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/disable-caching.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableCachingCsharp from './_disable-caching-csharp.mdx'; -import DisableCachingJava from './_disable-caching-java.mdx'; +import DisableCachingCsharp from './content/_disable-caching-csharp.mdx'; +import DisableCachingJava from './content/_disable-caching-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/get-database-and-server-statistics.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/get-database-and-server-statistics.mdx index 337c0c7c9b..455f7eec00 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/get-database-and-server-statistics.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/get-database-and-server-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseAndServerStatisticsCsharp from './_get-database-and-server-statistics-csharp.mdx'; -import GetDatabaseAndServerStatisticsJava from './_get-database-and-server-statistics-java.mdx'; -import GetDatabaseAndServerStatisticsHttp from './_get-database-and-server-statistics-http.mdx'; +import GetDatabaseAndServerStatisticsCsharp from './content/_get-database-and-server-statistics-csharp.mdx'; +import GetDatabaseAndServerStatisticsJava from './content/_get-database-and-server-statistics-java.mdx'; +import GetDatabaseAndServerStatisticsHttp from './content/_get-database-and-server-statistics-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/get-database-configuration.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/get-database-configuration.mdx index 8bdcbb6d78..28ef7c3272 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/get-database-configuration.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/get-database-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseConfigurationCsharp from './_get-database-configuration-csharp.mdx'; -import GetDatabaseConfigurationJava from './_get-database-configuration-java.mdx'; -import GetDatabaseConfigurationHttp from './_get-database-configuration-http.mdx'; +import GetDatabaseConfigurationCsharp from './content/_get-database-configuration-csharp.mdx'; +import GetDatabaseConfigurationJava from './content/_get-database-configuration-java.mdx'; +import GetDatabaseConfigurationHttp from './content/_get-database-configuration-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/get-full-url-for-a-document.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/get-full-url-for-a-document.mdx index 46e7f159ff..c6b06afa22 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/get-full-url-for-a-document.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/get-full-url-for-a-document.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetFullUrlForADocumentCsharp from './_get-full-url-for-a-document-csharp.mdx'; -import GetFullUrlForADocumentJava from './_get-full-url-for-a-document-java.mdx'; +import GetFullUrlForADocumentCsharp from './content/_get-full-url-for-a-document-csharp.mdx'; +import GetFullUrlForADocumentJava from './content/_get-full-url-for-a-document-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx index 8ead334768..9c4558a8e2 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesOfAllDatabasesOnAServerCsharp from './_get-names-of-all-databases-on-a-server-csharp.mdx'; -import GetNamesOfAllDatabasesOnAServerJava from './_get-names-of-all-databases-on-a-server-java.mdx'; -import GetNamesOfAllDatabasesOnAServerHttp from './_get-names-of-all-databases-on-a-server-http.mdx'; +import GetNamesOfAllDatabasesOnAServerCsharp from './content/_get-names-of-all-databases-on-a-server-csharp.mdx'; +import GetNamesOfAllDatabasesOnAServerJava from './content/_get-names-of-all-databases-on-a-server-java.mdx'; +import GetNamesOfAllDatabasesOnAServerHttp from './content/_get-names-of-all-databases-on-a-server-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/get-server-build-number.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/get-server-build-number.mdx index 93387cf0fb..95d56e9833 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/get-server-build-number.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/get-server-build-number.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerBuildNumberCsharp from './_get-server-build-number-csharp.mdx'; -import GetServerBuildNumberJava from './_get-server-build-number-java.mdx'; -import GetServerBuildNumberHttp from './_get-server-build-number-http.mdx'; +import GetServerBuildNumberCsharp from './content/_get-server-build-number-csharp.mdx'; +import GetServerBuildNumberJava from './content/_get-server-build-number-java.mdx'; +import GetServerBuildNumberHttp from './content/_get-server-build-number-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/start-backup-restore-operations.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/start-backup-restore-operations.mdx index 196ec5549b..cdc2df66c4 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/start-backup-restore-operations.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/start-backup-restore-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartBackupRestoreOperationsCsharp from './_start-backup-restore-operations-csharp.mdx'; -import StartBackupRestoreOperationsJava from './_start-backup-restore-operations-java.mdx'; -import StartBackupRestoreOperationsHttp from './_start-backup-restore-operations-http.mdx'; +import StartBackupRestoreOperationsCsharp from './content/_start-backup-restore-operations-csharp.mdx'; +import StartBackupRestoreOperationsJava from './content/_start-backup-restore-operations-java.mdx'; +import StartBackupRestoreOperationsHttp from './content/_start-backup-restore-operations-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx index 77c163a21a..357c1f407d 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartStopIndexingAndGetIndexingStatusCsharp from './_start-stop-indexing-and-get-indexing-status-csharp.mdx'; -import StartStopIndexingAndGetIndexingStatusJava from './_start-stop-indexing-and-get-indexing-status-java.mdx'; -import StartStopIndexingAndGetIndexingStatusHttp from './_start-stop-indexing-and-get-indexing-status-http.mdx'; +import StartStopIndexingAndGetIndexingStatusCsharp from './content/_start-stop-indexing-and-get-indexing-status-csharp.mdx'; +import StartStopIndexingAndGetIndexingStatusJava from './content/_start-stop-indexing-and-get-indexing-status-java.mdx'; +import StartStopIndexingAndGetIndexingStatusHttp from './content/_start-stop-indexing-and-get-indexing-status-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-reducing.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-reducing.mdx index a7d08e83aa..6083caed34 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-reducing.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/start-stop-reducing.mdx @@ -8,7 +8,7 @@ supported_languages: ["http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartStopReducingHttp from './_start-stop-reducing-http.mdx'; +import StartStopReducingHttp from './content/_start-stop-reducing-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-credentials.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-credentials.mdx index 5efcd15ad4..c761aba857 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-credentials.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-credentials.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchCommandsCredentialsCsharp from './_switch-commands-credentials-csharp.mdx'; -import SwitchCommandsCredentialsJava from './_switch-commands-credentials-java.mdx'; +import SwitchCommandsCredentialsCsharp from './content/_switch-commands-credentials-csharp.mdx'; +import SwitchCommandsCredentialsJava from './content/_switch-commands-credentials-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-to-a-different-database.mdx b/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-to-a-different-database.mdx index 2faeac42a8..57e43ce4a7 100644 --- a/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-to-a-different-database.mdx +++ b/versioned_docs/version-3.0/client-api/commands/how-to/switch-commands-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchCommandsToADifferentDatabaseCsharp from './_switch-commands-to-a-different-database-csharp.mdx'; -import SwitchCommandsToADifferentDatabaseJava from './_switch-commands-to-a-different-database-java.mdx'; +import SwitchCommandsToADifferentDatabaseCsharp from './content/_switch-commands-to-a-different-database-csharp.mdx'; +import SwitchCommandsToADifferentDatabaseJava from './content/_switch-commands-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_delete-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_delete-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_delete-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_delete-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_delete-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_delete-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_delete-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_get-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_get-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_get-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_get-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_get-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_get-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_get-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_put-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_put-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_put-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_put-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_put-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/_put-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/_put-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/content/_put-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/delete.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/delete.mdx index 3b1eeceffc..bc959e7274 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/delete.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/get.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/get.mdx index 78fd5e2262..de0293dee5 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/get.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-lock-mode.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-lock-mode.mdx index cea5b64ae7..3dbceb3e7a 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-lock-mode.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-lock-mode.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeIndexLockModeCsharp from './_change-index-lock-mode-csharp.mdx'; -import ChangeIndexLockModeJava from './_change-index-lock-mode-java.mdx'; +import ChangeIndexLockModeCsharp from './content/_change-index-lock-mode-csharp.mdx'; +import ChangeIndexLockModeJava from './content/_change-index-lock-mode-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-priority.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-priority.mdx index fcf8018071..366df76f67 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-priority.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/change-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeIndexPriorityCsharp from './_change-index-priority-csharp.mdx'; -import ChangeIndexPriorityJava from './_change-index-priority-java.mdx'; +import ChangeIndexPriorityCsharp from './content/_change-index-priority-csharp.mdx'; +import ChangeIndexPriorityJava from './content/_change-index-priority-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx index 53d3ec3417..3f9595b48c 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfIndexHasChangedCsharp from './_check-if-index-has-changed-csharp.mdx'; -import CheckIfIndexHasChangedJava from './_check-if-index-has-changed-java.mdx'; -import CheckIfIndexHasChangedHttp from './_check-if-index-has-changed-http.mdx'; +import CheckIfIndexHasChangedCsharp from './content/_check-if-index-has-changed-csharp.mdx'; +import CheckIfIndexHasChangedJava from './content/_check-if-index-has-changed-java.mdx'; +import CheckIfIndexHasChangedHttp from './content/_check-if-index-has-changed-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-lock-mode-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-lock-mode-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-lock-mode-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-lock-mode-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-lock-mode-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-lock-mode-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-lock-mode-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-lock-mode-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-priority-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-priority-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-priority-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-priority-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_change-index-priority-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_change-index-priority-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_check-if-index-has-changed-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-merge-suggestions-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_get-index-terms-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_get-index-terms-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-http.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-http.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-java.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/indexes/how-to/_reset-index-java.mdx rename to versioned_docs/version-3.0/client-api/commands/indexes/how-to/content/_reset-index-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx index 289c6799bf..23ae6a0068 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexMergeSuggestionsCsharp from './_get-index-merge-suggestions-csharp.mdx'; -import GetIndexMergeSuggestionsJava from './_get-index-merge-suggestions-java.mdx'; -import GetIndexMergeSuggestionsHttp from './_get-index-merge-suggestions-http.mdx'; +import GetIndexMergeSuggestionsCsharp from './content/_get-index-merge-suggestions-csharp.mdx'; +import GetIndexMergeSuggestionsJava from './content/_get-index-merge-suggestions-java.mdx'; +import GetIndexMergeSuggestionsHttp from './content/_get-index-merge-suggestions-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-terms.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-terms.mdx index df8b0bcbaf..2d2d3b1fcc 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-terms.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/get-index-terms.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexTermsCsharp from './_get-index-terms-csharp.mdx'; -import GetIndexTermsJava from './_get-index-terms-java.mdx'; -import GetIndexTermsHttp from './_get-index-terms-http.mdx'; +import GetIndexTermsCsharp from './content/_get-index-terms-csharp.mdx'; +import GetIndexTermsJava from './content/_get-index-terms-java.mdx'; +import GetIndexTermsHttp from './content/_get-index-terms-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/reset-index.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/reset-index.mdx index 1a99792f5e..7897d1deee 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/how-to/reset-index.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/how-to/reset-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexHttp from './_reset-index-http.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexHttp from './content/_reset-index-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/indexes/put.mdx b/versioned_docs/version-3.0/client-api/commands/indexes/put.mdx index b00b3371b6..f3795ee945 100644 --- a/versioned_docs/version-3.0/client-api/commands/indexes/put.mdx +++ b/versioned_docs/version-3.0/client-api/commands/indexes/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-http.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-http.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-java.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-java.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-http.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-http.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-java.mdx b/versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/patches/_how-to-work-with-patch-requests-java.mdx rename to versioned_docs/version-3.0/client-api/commands/patches/content/_how-to-work-with-patch-requests-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx b/versioned_docs/version-3.0/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx index 87f42ae8f6..f9611a6591 100644 --- a/versioned_docs/version-3.0/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx +++ b/versioned_docs/version-3.0/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseJavascriptToPatchYourDocumentsCsharp from './_how-to-use-javascript-to-patch-your-documents-csharp.mdx'; -import HowToUseJavascriptToPatchYourDocumentsJava from './_how-to-use-javascript-to-patch-your-documents-java.mdx'; -import HowToUseJavascriptToPatchYourDocumentsHttp from './_how-to-use-javascript-to-patch-your-documents-http.mdx'; +import HowToUseJavascriptToPatchYourDocumentsCsharp from './content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx'; +import HowToUseJavascriptToPatchYourDocumentsJava from './content/_how-to-use-javascript-to-patch-your-documents-java.mdx'; +import HowToUseJavascriptToPatchYourDocumentsHttp from './content/_how-to-use-javascript-to-patch-your-documents-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/patches/how-to-work-with-patch-requests.mdx b/versioned_docs/version-3.0/client-api/commands/patches/how-to-work-with-patch-requests.mdx index 68f473a7f2..86bc26b036 100644 --- a/versioned_docs/version-3.0/client-api/commands/patches/how-to-work-with-patch-requests.mdx +++ b/versioned_docs/version-3.0/client-api/commands/patches/how-to-work-with-patch-requests.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithPatchRequestsCsharp from './_how-to-work-with-patch-requests-csharp.mdx'; -import HowToWorkWithPatchRequestsJava from './_how-to-work-with-patch-requests-java.mdx'; -import HowToWorkWithPatchRequestsHttp from './_how-to-work-with-patch-requests-http.mdx'; +import HowToWorkWithPatchRequestsCsharp from './content/_how-to-work-with-patch-requests-csharp.mdx'; +import HowToWorkWithPatchRequestsJava from './content/_how-to-work-with-patch-requests-java.mdx'; +import HowToWorkWithPatchRequestsHttp from './content/_how-to-work-with-patch-requests-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-http.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-http.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-java.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-query-a-database-java.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-query-a-database-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-http.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-http.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-http.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-http.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-java.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-facet-query-java.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-facet-query-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-http.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-http.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-java.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-morelikethis-query-java.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-http.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-http.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-java.mdx b/versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/querying/_how-to-work-with-suggestion-query-java.mdx rename to versioned_docs/version-3.0/client-api/commands/querying/content/_how-to-work-with-suggestion-query-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/querying/how-to-query-a-database.mdx b/versioned_docs/version-3.0/client-api/commands/querying/how-to-query-a-database.mdx index a4176931b1..9b2f03c01d 100644 --- a/versioned_docs/version-3.0/client-api/commands/querying/how-to-query-a-database.mdx +++ b/versioned_docs/version-3.0/client-api/commands/querying/how-to-query-a-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryADatabaseCsharp from './_how-to-query-a-database-csharp.mdx'; -import HowToQueryADatabaseJava from './_how-to-query-a-database-java.mdx'; -import HowToQueryADatabaseHttp from './_how-to-query-a-database-http.mdx'; +import HowToQueryADatabaseCsharp from './content/_how-to-query-a-database-csharp.mdx'; +import HowToQueryADatabaseJava from './content/_how-to-query-a-database-java.mdx'; +import HowToQueryADatabaseHttp from './content/_how-to-query-a-database-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/querying/how-to-stream-query-results.mdx b/versioned_docs/version-3.0/client-api/commands/querying/how-to-stream-query-results.mdx index d5880a64ec..2c444a3955 100644 --- a/versioned_docs/version-3.0/client-api/commands/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-3.0/client-api/commands/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsHttp from './_how-to-stream-query-results-http.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsHttp from './content/_how-to-stream-query-results-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-facet-query.mdx b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-facet-query.mdx index e46a82616f..1ae5ef8efe 100644 --- a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-facet-query.mdx +++ b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-facet-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithFacetQueryCsharp from './_how-to-work-with-facet-query-csharp.mdx'; -import HowToWorkWithFacetQueryJava from './_how-to-work-with-facet-query-java.mdx'; -import HowToWorkWithFacetQueryHttp from './_how-to-work-with-facet-query-http.mdx'; +import HowToWorkWithFacetQueryCsharp from './content/_how-to-work-with-facet-query-csharp.mdx'; +import HowToWorkWithFacetQueryJava from './content/_how-to-work-with-facet-query-java.mdx'; +import HowToWorkWithFacetQueryHttp from './content/_how-to-work-with-facet-query-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx index 3086bb0a29..71c7e0a2b8 100644 --- a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx +++ b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithMorelikethisQueryCsharp from './_how-to-work-with-morelikethis-query-csharp.mdx'; -import HowToWorkWithMorelikethisQueryJava from './_how-to-work-with-morelikethis-query-java.mdx'; -import HowToWorkWithMorelikethisQueryHttp from './_how-to-work-with-morelikethis-query-http.mdx'; +import HowToWorkWithMorelikethisQueryCsharp from './content/_how-to-work-with-morelikethis-query-csharp.mdx'; +import HowToWorkWithMorelikethisQueryJava from './content/_how-to-work-with-morelikethis-query-java.mdx'; +import HowToWorkWithMorelikethisQueryHttp from './content/_how-to-work-with-morelikethis-query-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-suggestion-query.mdx b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-suggestion-query.mdx index 75d35334ac..2e366b7a84 100644 --- a/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-suggestion-query.mdx +++ b/versioned_docs/version-3.0/client-api/commands/querying/how-to-work-with-suggestion-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionQueryCsharp from './_how-to-work-with-suggestion-query-csharp.mdx'; -import HowToWorkWithSuggestionQueryJava from './_how-to-work-with-suggestion-query-java.mdx'; -import HowToWorkWithSuggestionQueryHttp from './_how-to-work-with-suggestion-query-http.mdx'; +import HowToWorkWithSuggestionQueryCsharp from './content/_how-to-work-with-suggestion-query-csharp.mdx'; +import HowToWorkWithSuggestionQueryJava from './content/_how-to-work-with-suggestion-query-java.mdx'; +import HowToWorkWithSuggestionQueryHttp from './content/_how-to-work-with-suggestion-query-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_delete-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_delete-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_delete-http.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_delete-http.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_delete-java.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_delete-java.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_delete-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_get-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_get-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_get-http.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_get-http.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_get-java.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_get-java.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_get-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_put-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_put-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_put-http.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_put-http.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_put-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/_put-java.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/_put-java.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/content/_put-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/delete.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/delete.mdx index bebeffe4df..b4665f4088 100644 --- a/versioned_docs/version-3.0/client-api/commands/transformers/delete.mdx +++ b/versioned_docs/version-3.0/client-api/commands/transformers/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/get.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/get.mdx index d7be4372d9..e7611ae03f 100644 --- a/versioned_docs/version-3.0/client-api/commands/transformers/get.mdx +++ b/versioned_docs/version-3.0/client-api/commands/transformers/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx index 0712d524c0..f7909e6b51 100644 --- a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx +++ b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeTransformerLockModeCsharp from './_change-transformer-lock-mode-csharp.mdx'; -import ChangeTransformerLockModeJava from './_change-transformer-lock-mode-java.mdx'; -import ChangeTransformerLockModeHttp from './_change-transformer-lock-mode-http.mdx'; +import ChangeTransformerLockModeCsharp from './content/_change-transformer-lock-mode-csharp.mdx'; +import ChangeTransformerLockModeJava from './content/_change-transformer-lock-mode-java.mdx'; +import ChangeTransformerLockModeHttp from './content/_change-transformer-lock-mode-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-http.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-http.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-java.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_change-transformer-lock-mode-java.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-csharp.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-csharp.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-http.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-http.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-http.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-http.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-java.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/commands/transformers/how-to/_transform-query-results-java.mdx rename to versioned_docs/version-3.0/client-api/commands/transformers/how-to/content/_transform-query-results-java.mdx diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/transform-query-results.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/transform-query-results.mdx index cf34643517..ca07a031b1 100644 --- a/versioned_docs/version-3.0/client-api/commands/transformers/how-to/transform-query-results.mdx +++ b/versioned_docs/version-3.0/client-api/commands/transformers/how-to/transform-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TransformQueryResultsCsharp from './_transform-query-results-csharp.mdx'; -import TransformQueryResultsJava from './_transform-query-results-java.mdx'; -import TransformQueryResultsHttp from './_transform-query-results-http.mdx'; +import TransformQueryResultsCsharp from './content/_transform-query-results-csharp.mdx'; +import TransformQueryResultsJava from './content/_transform-query-results-java.mdx'; +import TransformQueryResultsHttp from './content/_transform-query-results-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/transformers/put.mdx b/versioned_docs/version-3.0/client-api/commands/transformers/put.mdx index c262076493..c87b5c1ced 100644 --- a/versioned_docs/version-3.0/client-api/commands/transformers/put.mdx +++ b/versioned_docs/version-3.0/client-api/commands/transformers/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/commands/what-are-commands.mdx b/versioned_docs/version-3.0/client-api/commands/what-are-commands.mdx index a1f7fbf7b1..353d1c9ac9 100644 --- a/versioned_docs/version-3.0/client-api/commands/what-are-commands.mdx +++ b/versioned_docs/version-3.0/client-api/commands/what-are-commands.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreCommandsCsharp from './_what-are-commands-csharp.mdx'; -import WhatAreCommandsJava from './_what-are-commands-java.mdx'; -import WhatAreCommandsHttp from './_what-are-commands-http.mdx'; +import WhatAreCommandsCsharp from './content/_what-are-commands-csharp.mdx'; +import WhatAreCommandsJava from './content/_what-are-commands-java.mdx'; +import WhatAreCommandsHttp from './content/_what-are-commands-http.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/caching.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/caching.mdx index 6d4977909d..4dabb4ef14 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/caching.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CachingCsharp from './_caching-csharp.mdx'; -import CachingJava from './_caching-java.mdx'; +import CachingCsharp from './content/_caching-csharp.mdx'; +import CachingJava from './content/_caching-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_caching-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_caching-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_caching-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_caching-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_caching-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_caching-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_caching-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_misc-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_misc-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_misc-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_misc-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_misc-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_misc-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_misc-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_misc-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_querying-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_querying-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_querying-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_querying-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_querying-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_querying-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_replication-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_replication-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_replication-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_replication-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_replication-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_replication-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_replication-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_replication-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_request-handling-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_request-handling-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_request-handling-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_request-handling-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_request-handling-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_request-handling-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_request-handling-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_request-handling-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_what-are-conventions-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_what-are-conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_what-are-conventions-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_what-are-conventions-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/_what-are-conventions-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/content/_what-are-conventions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/_what-are-conventions-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/content/_what-are-conventions-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_global-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_global-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_global-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/global.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/global.mdx index cff4d2d4ac..4b5cb4e368 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/global.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/global.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/type-specific.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/type-specific.mdx index 20b5e53b78..2e28d95b3f 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/identifier-generation/type-specific.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/misc.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/misc.mdx index 406687d77b..5bef509f9b 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/misc.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/misc.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MiscCsharp from './_misc-csharp.mdx'; -import MiscJava from './_misc-java.mdx'; +import MiscCsharp from './content/_misc-csharp.mdx'; +import MiscJava from './content/_misc-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/querying.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/querying.mdx index def33fc71a..733f22d7ef 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/querying.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/replication.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/replication.mdx index 2bc5903cba..4bda52a73a 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/replication.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/replication.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReplicationCsharp from './_replication-csharp.mdx'; -import ReplicationJava from './_replication-java.mdx'; +import ReplicationCsharp from './content/_replication-csharp.mdx'; +import ReplicationJava from './content/_replication-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/request-handling.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/request-handling.mdx index 2172aa3623..61823f00ac 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/request-handling.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/request-handling.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RequestHandlingCsharp from './_request-handling-csharp.mdx'; -import RequestHandlingJava from './_request-handling-java.mdx'; +import RequestHandlingCsharp from './content/_request-handling-csharp.mdx'; +import RequestHandlingJava from './content/_request-handling-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/configuration/conventions/what-are-conventions.mdx b/versioned_docs/version-3.0/client-api/configuration/conventions/what-are-conventions.mdx index a7a4955523..d1f0819d22 100644 --- a/versioned_docs/version-3.0/client-api/configuration/conventions/what-are-conventions.mdx +++ b/versioned_docs/version-3.0/client-api/configuration/conventions/what-are-conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConventionsCsharp from './_what-are-conventions-csharp.mdx'; -import WhatAreConventionsJava from './_what-are-conventions-java.mdx'; +import WhatAreConventionsCsharp from './content/_what-are-conventions-csharp.mdx'; +import WhatAreConventionsJava from './content/_what-are-conventions-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-3.0/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-3.0/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/_creating-document-store-java.mdx b/versioned_docs/version-3.0/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-3.0/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-3.0/client-api/_setting-up-connection-string-csharp.mdx b/versioned_docs/version-3.0/client-api/content/_setting-up-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_setting-up-connection-string-csharp.mdx rename to versioned_docs/version-3.0/client-api/content/_setting-up-connection-string-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/_setting-up-connection-string-java.mdx b/versioned_docs/version-3.0/client-api/content/_setting-up-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_setting-up-connection-string-java.mdx rename to versioned_docs/version-3.0/client-api/content/_setting-up-connection-string-java.mdx diff --git a/versioned_docs/version-3.0/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-3.0/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-3.0/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-3.0/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-3.0/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-3.0/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-3.0/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-3.0/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-3.0/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-3.0/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-3.0/client-api/creating-document-store.mdx b/versioned_docs/version-3.0/client-api/creating-document-store.mdx index 308b21972e..34dfe3abf0 100644 --- a/versioned_docs/version-3.0/client-api/creating-document-store.mdx +++ b/versioned_docs/version-3.0/client-api/creating-document-store.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_events-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_events-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_events-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_events-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_events-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_events-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_events-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_events-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-delete-data-subscription-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-delete-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-delete-data-subscription-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-delete-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-delete-data-subscription-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-delete-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-delete-data-subscription-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-delete-data-subscription-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-get-subscriptions-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-get-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-get-subscriptions-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-get-subscriptions-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-get-subscriptions-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-get-subscriptions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-get-subscriptions-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-get-subscriptions-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-open-data-subscription-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-open-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-open-data-subscription-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-open-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-open-data-subscription-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-open-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-open-data-subscription-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-open-data-subscription-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-release-data-subscription-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-release-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-release-data-subscription-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-release-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-release-data-subscription-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-release-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_how-to-release-data-subscription-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_how-to-release-data-subscription-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx rename to versioned_docs/version-3.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/events.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/events.mdx index 7a984b50df..37df376812 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/events.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/events.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EventsCsharp from './_events-csharp.mdx'; -import EventsJava from './_events-java.mdx'; +import EventsCsharp from './content/_events-csharp.mdx'; +import EventsJava from './content/_events-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-create-data-subscription.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-create-data-subscription.mdx index a7a5a98486..ad5b46e9a4 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-create-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-delete-data-subscription.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-delete-data-subscription.mdx index 09769c756c..2e6519556a 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-delete-data-subscription.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-delete-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDeleteDataSubscriptionCsharp from './_how-to-delete-data-subscription-csharp.mdx'; -import HowToDeleteDataSubscriptionJava from './_how-to-delete-data-subscription-java.mdx'; +import HowToDeleteDataSubscriptionCsharp from './content/_how-to-delete-data-subscription-csharp.mdx'; +import HowToDeleteDataSubscriptionJava from './content/_how-to-delete-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-get-subscriptions.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-get-subscriptions.mdx index 88bce1312e..037610a4ac 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-get-subscriptions.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-get-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetSubscriptionsCsharp from './_how-to-get-subscriptions-csharp.mdx'; -import HowToGetSubscriptionsJava from './_how-to-get-subscriptions-java.mdx'; +import HowToGetSubscriptionsCsharp from './content/_how-to-get-subscriptions-csharp.mdx'; +import HowToGetSubscriptionsJava from './content/_how-to-get-subscriptions-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-open-data-subscription.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-open-data-subscription.mdx index da4c1f3961..61b7884c7d 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-open-data-subscription.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-open-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToOpenDataSubscriptionCsharp from './_how-to-open-data-subscription-csharp.mdx'; -import HowToOpenDataSubscriptionJava from './_how-to-open-data-subscription-java.mdx'; +import HowToOpenDataSubscriptionCsharp from './content/_how-to-open-data-subscription-csharp.mdx'; +import HowToOpenDataSubscriptionJava from './content/_how-to-open-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-release-data-subscription.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-release-data-subscription.mdx index 9becdf05d7..c1ea5f9308 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-release-data-subscription.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/how-to-release-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToReleaseDataSubscriptionCsharp from './_how-to-release-data-subscription-csharp.mdx'; -import HowToReleaseDataSubscriptionJava from './_how-to-release-data-subscription-java.mdx'; +import HowToReleaseDataSubscriptionCsharp from './content/_how-to-release-data-subscription-csharp.mdx'; +import HowToReleaseDataSubscriptionJava from './content/_how-to-release-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-3.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 2b339597f2..967ee7cf59 100644 --- a/versioned_docs/version-3.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-3.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/how-to/_enable-profiling-csharp.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_enable-profiling-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_enable-profiling-csharp.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_enable-profiling-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-java.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-java.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-java.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_work-with-authentication-csharp.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_work-with-authentication-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_work-with-authentication-csharp.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_work-with-authentication-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/_work-with-authentication-java.mdx b/versioned_docs/version-3.0/client-api/how-to/content/_work-with-authentication-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/how-to/_work-with-authentication-java.mdx rename to versioned_docs/version-3.0/client-api/how-to/content/_work-with-authentication-java.mdx diff --git a/versioned_docs/version-3.0/client-api/how-to/enable-profiling.mdx b/versioned_docs/version-3.0/client-api/how-to/enable-profiling.mdx index a6c75be981..87ce5c3694 100644 --- a/versioned_docs/version-3.0/client-api/how-to/enable-profiling.mdx +++ b/versioned_docs/version-3.0/client-api/how-to/enable-profiling.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableProfilingCsharp from './_enable-profiling-csharp.mdx'; +import EnableProfilingCsharp from './content/_enable-profiling-csharp.mdx'; diff --git a/versioned_docs/version-3.0/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx b/versioned_docs/version-3.0/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx index bff961b266..66b4eee05c 100644 --- a/versioned_docs/version-3.0/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx +++ b/versioned_docs/version-3.0/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SendCustomRequestUsingHttpjsonrequestfactoryCsharp from './_send-custom-request-using-httpjsonrequestfactory-csharp.mdx'; -import SendCustomRequestUsingHttpjsonrequestfactoryJava from './_send-custom-request-using-httpjsonrequestfactory-java.mdx'; +import SendCustomRequestUsingHttpjsonrequestfactoryCsharp from './content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx'; +import SendCustomRequestUsingHttpjsonrequestfactoryJava from './content/_send-custom-request-using-httpjsonrequestfactory-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-3.0/client-api/how-to/setup-aggressive-caching.mdx index 3020188adb..970f58ef18 100644 --- a/versioned_docs/version-3.0/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-3.0/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/how-to/work-with-authentication.mdx b/versioned_docs/version-3.0/client-api/how-to/work-with-authentication.mdx index 94664db7d5..e9bf7b11f9 100644 --- a/versioned_docs/version-3.0/client-api/how-to/work-with-authentication.mdx +++ b/versioned_docs/version-3.0/client-api/how-to/work-with-authentication.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkWithAuthenticationCsharp from './_work-with-authentication-csharp.mdx'; -import WorkWithAuthenticationJava from './_work-with-authentication-java.mdx'; +import WorkWithAuthenticationCsharp from './content/_work-with-authentication-csharp.mdx'; +import WorkWithAuthenticationJava from './content/_work-with-authentication-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-listeners-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-listeners-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-listeners-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-listeners-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-listeners-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-listeners-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-listeners-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.0/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.0/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx index 27817c3a65..3eecbd1c26 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConflictListenersAndHowToWorkWithThemCsharp from './_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreConflictListenersAndHowToWorkWithThemJava from './_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreConflictListenersAndHowToWorkWithThemCsharp from './content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreConflictListenersAndHowToWorkWithThemJava from './content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx index 3b73745d1e..1b441401e0 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConversionListenersAndHowToWorkWithThemCsharp from './_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreConversionListenersAndHowToWorkWithThemJava from './_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreConversionListenersAndHowToWorkWithThemCsharp from './content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreConversionListenersAndHowToWorkWithThemJava from './content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx index 0eaf2e0353..363f29f0c1 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDeleteListenersAndHowToWorkWithThemCsharp from './_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreDeleteListenersAndHowToWorkWithThemJava from './_what-are-delete-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreDeleteListenersAndHowToWorkWithThemCsharp from './content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreDeleteListenersAndHowToWorkWithThemJava from './content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-listeners.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-listeners.mdx index e69346f0a4..6771419303 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-listeners.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-listeners.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreListenersCsharp from './_what-are-listeners-csharp.mdx'; -import WhatAreListenersJava from './_what-are-listeners-java.mdx'; +import WhatAreListenersCsharp from './content/_what-are-listeners-csharp.mdx'; +import WhatAreListenersJava from './content/_what-are-listeners-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx index 4e58413a84..ede72a5938 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreQueryListenersAndHowToWorkWithThemCsharp from './_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreQueryListenersAndHowToWorkWithThemJava from './_what-are-query-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreQueryListenersAndHowToWorkWithThemCsharp from './content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreQueryListenersAndHowToWorkWithThemJava from './content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.0/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx index 09d609feec..0b02d97661 100644 --- a/versioned_docs/version-3.0/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.0/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreStoreListenersAndHowToWorkWithThemCsharp from './_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreStoreListenersAndHowToWorkWithThemJava from './_what-are-store-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreStoreListenersAndHowToWorkWithThemCsharp from './content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreStoreListenersAndHowToWorkWithThemJava from './content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-3.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-3.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index fcb5b3dd1d..ece2d33b1f 100644 --- a/versioned_docs/version-3.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-3.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-3.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 971a61f3fc..cdeebd7e41 100644 --- a/versioned_docs/version-3.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-3.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-3.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-3.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-3.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/deleting-entities.mdx b/versioned_docs/version-3.0/client-api/session/deleting-entities.mdx index b2a387fd2b..9b35690fb0 100644 --- a/versioned_docs/version-3.0/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-3.0/client-api/session/deleting-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-3.0/client-api/session/how-to/check-if-entity-has-changed.mdx index d4312b3f1d..f100e72b8e 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-3.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index aed985225e..4667c7cf4e 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-3.0/client-api/session/how-to/clear-a-session.mdx index e0f42b1690..dc776c029f 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/clear-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-etag-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-etag-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-etag-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-etag-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-etag-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-etag-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-etag-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-etag-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-metadata-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-metadata-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-metadata-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-metadata-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-metadata-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-url-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-url-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-url-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-url-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_get-entity-url-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-url-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_get-entity-url-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_get-entity-url-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_mark-entity-as-readonly-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_mark-entity-as-readonly-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_mark-entity-as-readonly-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_mark-entity-as-readonly-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_mark-entity-as-readonly-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_mark-entity-as-readonly-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_mark-entity-as-readonly-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_mark-entity-as-readonly-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_perform-operations-lazily-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_perform-operations-lazily-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_perform-operations-lazily-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_perform-operations-lazily-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_use-morelikethis-csharp.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_use-morelikethis-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/_use-morelikethis-java.mdx b/versioned_docs/version-3.0/client-api/session/how-to/content/_use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/how-to/_use-morelikethis-java.mdx rename to versioned_docs/version-3.0/client-api/session/how-to/content/_use-morelikethis-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-3.0/client-api/session/how-to/defer-operations.mdx index b0aba07bd7..d3c8837b64 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-3.0/client-api/session/how-to/evict-entity-from-a-session.mdx index 9a908c6884..7421ee87f4 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-etag.mdx b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-etag.mdx index 496a20c047..e348419dde 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-etag.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-etag.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityEtagCsharp from './_get-entity-etag-csharp.mdx'; -import GetEntityEtagJava from './_get-entity-etag-java.mdx'; +import GetEntityEtagCsharp from './content/_get-entity-etag-csharp.mdx'; +import GetEntityEtagJava from './content/_get-entity-etag-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-id.mdx index 164c11f2c6..4bc64cc539 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-id.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-metadata.mdx b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-metadata.mdx index fceb8bde14..f5ef9f96fd 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-metadata.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-metadata.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityMetadataCsharp from './_get-entity-metadata-csharp.mdx'; -import GetEntityMetadataJava from './_get-entity-metadata-java.mdx'; +import GetEntityMetadataCsharp from './content/_get-entity-metadata-csharp.mdx'; +import GetEntityMetadataJava from './content/_get-entity-metadata-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-url.mdx b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-url.mdx index 291fd667bd..068ed6faf2 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/get-entity-url.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/get-entity-url.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityUrlCsharp from './_get-entity-url-csharp.mdx'; -import GetEntityUrlJava from './_get-entity-url-java.mdx'; +import GetEntityUrlCsharp from './content/_get-entity-url-csharp.mdx'; +import GetEntityUrlJava from './content/_get-entity-url-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/mark-entity-as-readonly.mdx b/versioned_docs/version-3.0/client-api/session/how-to/mark-entity-as-readonly.mdx index 606dc417ea..236adf2ef3 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/mark-entity-as-readonly.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/mark-entity-as-readonly.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MarkEntityAsReadonlyCsharp from './_mark-entity-as-readonly-csharp.mdx'; -import MarkEntityAsReadonlyJava from './_mark-entity-as-readonly-java.mdx'; +import MarkEntityAsReadonlyCsharp from './content/_mark-entity-as-readonly-csharp.mdx'; +import MarkEntityAsReadonlyJava from './content/_mark-entity-as-readonly-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-3.0/client-api/session/how-to/perform-operations-lazily.mdx index 5511326bef..986f73f7f4 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyJava from './_perform-operations-lazily-java.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyJava from './content/_perform-operations-lazily-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-3.0/client-api/session/how-to/refresh-entity.mdx index 3e1fbc36fa..d8e9b9aa3d 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/refresh-entity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/how-to/use-morelikethis.mdx b/versioned_docs/version-3.0/client-api/session/how-to/use-morelikethis.mdx index edeb1c556d..21b45430cb 100644 --- a/versioned_docs/version-3.0/client-api/session/how-to/use-morelikethis.mdx +++ b/versioned_docs/version-3.0/client-api/session/how-to/use-morelikethis.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseMorelikethisCsharp from './_use-morelikethis-csharp.mdx'; -import UseMorelikethisJava from './_use-morelikethis-java.mdx'; +import UseMorelikethisCsharp from './content/_use-morelikethis-csharp.mdx'; +import UseMorelikethisJava from './content/_use-morelikethis-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/loading-entities.mdx b/versioned_docs/version-3.0/client-api/session/loading-entities.mdx index 6a3978f9d2..3305d805b8 100644 --- a/versioned_docs/version-3.0/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-3.0/client-api/session/loading-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/opening-a-session.mdx b/versioned_docs/version-3.0/client-api/session/opening-a-session.mdx index e01e531ad0..e77a7a419b 100644 --- a/versioned_docs/version-3.0/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-3.0/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-multifaceted-search-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-multifaceted-search-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-multifaceted-search-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-a-multifaceted-search-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-dynamic-aggregation-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-dynamic-aggregation-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-dynamic-aggregation-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-dynamic-aggregation-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-projection-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-projection-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-projection-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-projection-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-projection-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-projection-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-projection-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-projection-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-query-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-query-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-query-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-search-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-search-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-search-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-search-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-transformers-in-queries-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-transformers-in-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-transformers-in-queries-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-transformers-in-queries-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-use-transformers-in-queries-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-transformers-in-queries-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-use-transformers-in-queries-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-use-transformers-in-queries-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-customize-query.mdx index 62d4da6902..3341c59a3f 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-customize-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-get-query-statistics.mdx index 94718125d1..3c036f0714 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 1b87a429e5..5c25ce1be5 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx index a71b58451a..61b934ca0e 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAMultifacetedSearchCsharp from './_how-to-perform-a-multifaceted-search-csharp.mdx'; -import HowToPerformAMultifacetedSearchJava from './_how-to-perform-a-multifaceted-search-java.mdx'; +import HowToPerformAMultifacetedSearchCsharp from './content/_how-to-perform-a-multifaceted-search-csharp.mdx'; +import HowToPerformAMultifacetedSearchJava from './content/_how-to-perform-a-multifaceted-search-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx index 0a3e1ad54b..fbc60ddfcb 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformDynamicAggregationCsharp from './_how-to-perform-dynamic-aggregation-csharp.mdx'; -import HowToPerformDynamicAggregationJava from './_how-to-perform-dynamic-aggregation-java.mdx'; +import HowToPerformDynamicAggregationCsharp from './content/_how-to-perform-dynamic-aggregation-csharp.mdx'; +import HowToPerformDynamicAggregationJava from './content/_how-to-perform-dynamic-aggregation-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-projection.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-projection.mdx index 6ab93ad467..16828a1831 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-projection.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-projection.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProjectionCsharp from './_how-to-perform-projection-csharp.mdx'; -import HowToPerformProjectionJava from './_how-to-perform-projection-java.mdx'; +import HowToPerformProjectionCsharp from './content/_how-to-perform-projection-csharp.mdx'; +import HowToPerformProjectionJava from './content/_how-to-perform-projection-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-queries-lazily.mdx index e5f0b90037..478337c56f 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-query-a-spatial-index.mdx index 1811c4b2aa..194ffede17 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-query.mdx index c46ccff1b8..9ee79db66c 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryJava from './_how-to-query-java.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryJava from './content/_how-to-query-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-stream-query-results.mdx index eddda14f7e..c30d388a07 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-highlighting.mdx index 94b03e2b95..b501af271c 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-intersect.mdx index bd059a2608..710a04f0cf 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-intersect.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-search.mdx index 61347b249c..e0b6197771 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; -import HowToUseSearchJava from './_how-to-use-search-java.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; +import HowToUseSearchJava from './content/_how-to-use-search-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-transformers-in-queries.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-transformers-in-queries.mdx index f345d016a5..5e14b3817c 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-use-transformers-in-queries.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-use-transformers-in-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseTransformersInQueriesCsharp from './_how-to-use-transformers-in-queries-csharp.mdx'; -import HowToUseTransformersInQueriesJava from './_how-to-use-transformers-in-queries-java.mdx'; +import HowToUseTransformersInQueriesCsharp from './content/_how-to-use-transformers-in-queries-csharp.mdx'; +import HowToUseTransformersInQueriesJava from './content/_how-to-use-transformers-in-queries-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-3.0/client-api/session/querying/how-to-work-with-suggestions.mdx index 19770b6e7a..cbb8118d39 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-not-operator-java.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-3.0/client-api/session/querying/lucene/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-3.0/client-api/session/querying/lucene/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx index 623d2ba14b..b32205af4e 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneInQueriesCsharp from './_how-to-use-lucene-in-queries-csharp.mdx'; -import HowToUseLuceneInQueriesJava from './_how-to-use-lucene-in-queries-java.mdx'; +import HowToUseLuceneInQueriesCsharp from './content/_how-to-use-lucene-in-queries-csharp.mdx'; +import HowToUseLuceneInQueriesJava from './content/_how-to-use-lucene-in-queries-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-not-operator.mdx b/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-not-operator.mdx index 007cfe87b7..5ea970d99a 100644 --- a/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-not-operator.mdx +++ b/versioned_docs/version-3.0/client-api/session/querying/lucene/how-to-use-not-operator.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/saving-changes.mdx b/versioned_docs/version-3.0/client-api/session/saving-changes.mdx index d6eb790444..94a1964999 100644 --- a/versioned_docs/version-3.0/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-3.0/client-api/session/saving-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/storing-entities.mdx b/versioned_docs/version-3.0/client-api/session/storing-entities.mdx index c65914af09..a17691ac86 100644 --- a/versioned_docs/version-3.0/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-3.0/client-api/session/storing-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-3.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx index f1b3580240..88123ae524 100644 --- a/versioned_docs/version-3.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-3.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/setting-up-connection-string.mdx b/versioned_docs/version-3.0/client-api/setting-up-connection-string.mdx index d174b93ec6..1a4f066af0 100644 --- a/versioned_docs/version-3.0/client-api/setting-up-connection-string.mdx +++ b/versioned_docs/version-3.0/client-api/setting-up-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpConnectionStringCsharp from './_setting-up-connection-string-csharp.mdx'; -import SettingUpConnectionStringJava from './_setting-up-connection-string-java.mdx'; +import SettingUpConnectionStringCsharp from './content/_setting-up-connection-string-csharp.mdx'; +import SettingUpConnectionStringJava from './content/_setting-up-connection-string-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/setting-up-default-database.mdx b/versioned_docs/version-3.0/client-api/setting-up-default-database.mdx index f42e60e512..50fe3a0709 100644 --- a/versioned_docs/version-3.0/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-3.0/client-api/setting-up-default-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; diff --git a/versioned_docs/version-3.0/client-api/what-is-a-document-store.mdx b/versioned_docs/version-3.0/client-api/what-is-a-document-store.mdx index d197224f3c..d35f2153fb 100644 --- a/versioned_docs/version-3.0/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-3.0/client-api/what-is-a-document-store.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-configuration-changes-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-configuration-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-configuration-changes-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-configuration-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-conflicts-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-conflicts-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-conflicts-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-conflicts-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-file-changes-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-file-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-file-changes-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-file-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-synchronization-notifications-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-synchronization-notifications-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/changes/_how-to-subscribe-synchronization-notifications-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/changes/content/_how-to-subscribe-synchronization-notifications-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx index 9de2861884..1a48144a97 100644 --- a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeConfigurationChangesCsharp from './_how-to-subscribe-configuration-changes-csharp.mdx'; +import HowToSubscribeConfigurationChangesCsharp from './content/_how-to-subscribe-configuration-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-conflicts.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-conflicts.mdx index 934d9b78aa..26f11b695d 100644 --- a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-conflicts.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-conflicts.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeConflictsCsharp from './_how-to-subscribe-conflicts-csharp.mdx'; +import HowToSubscribeConflictsCsharp from './content/_how-to-subscribe-conflicts-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-file-changes.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-file-changes.mdx index c00c28578b..89813e17a4 100644 --- a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-file-changes.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-file-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeFileChangesCsharp from './_how-to-subscribe-file-changes-csharp.mdx'; +import HowToSubscribeFileChangesCsharp from './content/_how-to-subscribe-file-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx index 0a34f512f7..8d78280972 100644 --- a/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeSynchronizationNotificationsCsharp from './_how-to-subscribe-synchronization-notifications-csharp.mdx'; +import HowToSubscribeSynchronizationNotificationsCsharp from './content/_how-to-subscribe-synchronization-notifications-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/backup-restore.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/backup-restore.mdx index 4808d86d27..5488e6ef1d 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/admin/backup-restore.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/admin/backup-restore.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BackupRestoreCsharp from './_backup-restore-csharp.mdx'; -import BackupRestoreHttp from './_backup-restore-http.mdx'; +import BackupRestoreCsharp from './content/_backup-restore-csharp.mdx'; +import BackupRestoreHttp from './content/_backup-restore-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/compaction.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/compaction.mdx index 33a7b036e7..5fc6e09762 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/admin/compaction.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/admin/compaction.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactionCsharp from './_compaction-csharp.mdx'; -import CompactionHttp from './_compaction-http.mdx'; +import CompactionCsharp from './content/_compaction-csharp.mdx'; +import CompactionHttp from './content/_compaction-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_backup-restore-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_backup-restore-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_backup-restore-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_backup-restore-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_backup-restore-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_backup-restore-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_backup-restore-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_backup-restore-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_compaction-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_compaction-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_compaction-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_compaction-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_compaction-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_compaction-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_compaction-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_compaction-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_manage-filesystems-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_manage-filesystems-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_manage-filesystems-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_manage-filesystems-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_manage-filesystems-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_manage-filesystems-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_manage-filesystems-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_manage-filesystems-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_reset-indexes-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_reset-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_reset-indexes-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_reset-indexes-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_reset-indexes-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_reset-indexes-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_reset-indexes-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_reset-indexes-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_stats-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_stats-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_stats-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_stats-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/_stats-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_stats-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/admin/_stats-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/admin/content/_stats-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/manage-filesystems.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/manage-filesystems.mdx index 98ae468d53..710a4b73fa 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/admin/manage-filesystems.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/admin/manage-filesystems.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ManageFilesystemsCsharp from './_manage-filesystems-csharp.mdx'; -import ManageFilesystemsHttp from './_manage-filesystems-http.mdx'; +import ManageFilesystemsCsharp from './content/_manage-filesystems-csharp.mdx'; +import ManageFilesystemsHttp from './content/_manage-filesystems-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/reset-indexes.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/reset-indexes.mdx index b13038f3ed..a66f1f1f05 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/admin/reset-indexes.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/admin/reset-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexesCsharp from './_reset-indexes-csharp.mdx'; -import ResetIndexesHttp from './_reset-indexes-http.mdx'; +import ResetIndexesCsharp from './content/_reset-indexes-csharp.mdx'; +import ResetIndexesHttp from './content/_reset-indexes-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/admin/stats.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/admin/stats.mdx index 70f5d56c83..debdbdb71b 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/admin/stats.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/admin/stats.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StatsCsharp from './_stats-csharp.mdx'; -import StatsHttp from './_stats-http.mdx'; +import StatsCsharp from './content/_stats-csharp.mdx'; +import StatsHttp from './content/_stats-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_delete-key-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_delete-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_delete-key-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_delete-key-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_delete-key-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_delete-key-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_delete-key-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_delete-key-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-names-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-names-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-names-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-names-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-names-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-names-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_get-key-names-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_get-key-names-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_search-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_search-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_search-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_search-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_search-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_search-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_search-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_set-key-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_set-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_set-key-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_set-key-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/_set-key-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_set-key-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/configurations/_set-key-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/configurations/content/_set-key-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/delete-key.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/delete-key.mdx index ec8dfe0637..6d1f8fdfba 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/delete-key.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/delete-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteKeyCsharp from './_delete-key-csharp.mdx'; -import DeleteKeyHttp from './_delete-key-http.mdx'; +import DeleteKeyCsharp from './content/_delete-key-csharp.mdx'; +import DeleteKeyHttp from './content/_delete-key-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key-names.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key-names.mdx index 87978489cc..c1e5098406 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key-names.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetKeyNamesCsharp from './_get-key-names-csharp.mdx'; -import GetKeyNamesHttp from './_get-key-names-http.mdx'; +import GetKeyNamesCsharp from './content/_get-key-names-csharp.mdx'; +import GetKeyNamesHttp from './content/_get-key-names-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key.mdx index 26966d811b..78942b0f5a 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/get-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetKeyCsharp from './_get-key-csharp.mdx'; -import GetKeyHttp from './_get-key-http.mdx'; +import GetKeyCsharp from './content/_get-key-csharp.mdx'; +import GetKeyHttp from './content/_get-key-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/search.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/search.mdx index 0de55710d2..4960e64d8e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/search.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchCsharp from './_search-csharp.mdx'; -import SearchHttp from './_search-http.mdx'; +import SearchCsharp from './content/_search-csharp.mdx'; +import SearchHttp from './content/_search-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/set-key.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/set-key.mdx index 9f1939f711..82b93f5b00 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/configurations/set-key.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/configurations/set-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetKeyCsharp from './_set-key-csharp.mdx'; -import SetKeyHttp from './_set-key-http.mdx'; +import SetKeyCsharp from './content/_set-key-csharp.mdx'; +import SetKeyHttp from './content/_set-key-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/browse-overview.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/browse-overview.mdx index 3d2dcb9986..7ce3021f72 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/browse-overview.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/browse-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BrowseOverviewCsharp from './_browse-overview-csharp.mdx'; -import BrowseOverviewHttp from './_browse-overview-http.mdx'; +import BrowseOverviewCsharp from './content/_browse-overview-csharp.mdx'; +import BrowseOverviewHttp from './content/_browse-overview-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_browse-overview-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_browse-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_browse-overview-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_browse-overview-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_browse-overview-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_browse-overview-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_browse-overview-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_browse-overview-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-directories-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-directories-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-directories-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-directories-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-directories-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-directories-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-directories-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-directories-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_get-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_starts-with-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_starts-with-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_starts-with-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_starts-with-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_starts-with-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_starts-with-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_starts-with-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_starts-with-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_stream-file-headers-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_stream-file-headers-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_stream-file-headers-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_stream-file-headers-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_stream-file-headers-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_stream-file-headers-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/browse/_stream-file-headers-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/browse/content/_stream-file-headers-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get-directories.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get-directories.mdx index c38acd0f6a..177ef3258c 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get-directories.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get-directories.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDirectoriesCsharp from './_get-directories-csharp.mdx'; -import GetDirectoriesHttp from './_get-directories-http.mdx'; +import GetDirectoriesCsharp from './content/_get-directories-csharp.mdx'; +import GetDirectoriesHttp from './content/_get-directories-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get.mdx index 74ca6b09ff..4b7e7f2a4a 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/starts-with.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/starts-with.mdx index 7f86d86fd4..65f0850649 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/starts-with.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/starts-with.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithCsharp from './_starts-with-csharp.mdx'; -import StartsWithHttp from './_starts-with-http.mdx'; +import StartsWithCsharp from './content/_starts-with-csharp.mdx'; +import StartsWithHttp from './content/_starts-with-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/stream-file-headers.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/stream-file-headers.mdx index 9d4f69627a..f2716459d8 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/stream-file-headers.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/browse/stream-file-headers.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamFileHeadersCsharp from './_stream-file-headers-csharp.mdx'; -import StreamFileHeadersHttp from './_stream-file-headers-http.mdx'; +import StreamFileHeadersCsharp from './content/_stream-file-headers-csharp.mdx'; +import StreamFileHeadersHttp from './content/_stream-file-headers-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_delete-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_delete-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_delete-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_delete-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_delete-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_download-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_download-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_download-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_download-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_download-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_download-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_download-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_download-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_rename-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_rename-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_rename-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_rename-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_rename-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_rename-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_rename-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_rename-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_upload-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_upload-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_upload-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_upload-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/_upload-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/content/_upload-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/_upload-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/content/_upload-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/delete.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/delete.mdx index 8b8910cd58..ddee33f8df 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/delete.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/download.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/download.mdx index 5ee6e63734..9179c7ef7a 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/download.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/download.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DownloadCsharp from './_download-csharp.mdx'; -import DownloadHttp from './_download-http.mdx'; +import DownloadCsharp from './content/_download-csharp.mdx'; +import DownloadHttp from './content/_download-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_get-metadata-for-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_get-metadata-for-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_get-metadata-for-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_get-metadata-for-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_get-metadata-for-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_get-metadata-for-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_get-metadata-for-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_get-metadata-for-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_update-metadata-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_update-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_update-metadata-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_update-metadata-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_update-metadata-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_update-metadata-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/_update-metadata-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/content/_update-metadata-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/get-metadata-for.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/get-metadata-for.mdx index 24b11cbbdc..139f80138b 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/get-metadata-for.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/get-metadata-for.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetMetadataForCsharp from './_get-metadata-for-csharp.mdx'; -import GetMetadataForHttp from './_get-metadata-for-http.mdx'; +import GetMetadataForCsharp from './content/_get-metadata-for-csharp.mdx'; +import GetMetadataForHttp from './content/_get-metadata-for-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/update-metadata.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/update-metadata.mdx index 6171ce317f..79fe48781e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/update-metadata.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/metadata/update-metadata.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateMetadataCsharp from './_update-metadata-csharp.mdx'; -import UpdateMetadataHttp from './_update-metadata-http.mdx'; +import UpdateMetadataCsharp from './content/_update-metadata-csharp.mdx'; +import UpdateMetadataHttp from './content/_update-metadata-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/rename.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/rename.mdx index 33fd2da641..b6e095a91e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/rename.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/rename.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RenameCsharp from './_rename-csharp.mdx'; -import RenameHttp from './_rename-http.mdx'; +import RenameCsharp from './content/_rename-csharp.mdx'; +import RenameHttp from './content/_rename-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_get-search-fields-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_get-search-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_get-search-fields-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_get-search-fields-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_get-search-fields-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_get-search-fields-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_get-search-fields-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_get-search-fields-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-on-directory-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-on-directory-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-on-directory-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-on-directory-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-on-directory-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-on-directory-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-on-directory-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-on-directory-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-overview-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-overview-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-overview-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-overview-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-overview-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/files/search/_search-overview-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/files/search/content/_search-overview-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/get-search-fields.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/get-search-fields.mdx index d0a50bb238..ad4781c9ee 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/get-search-fields.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/get-search-fields.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetSearchFieldsCsharp from './_get-search-fields-csharp.mdx'; -import GetSearchFieldsHttp from './_get-search-fields-http.mdx'; +import GetSearchFieldsCsharp from './content/_get-search-fields-csharp.mdx'; +import GetSearchFieldsHttp from './content/_get-search-fields-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-on-directory.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-on-directory.mdx index be2f224032..fbf839babc 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-on-directory.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-on-directory.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchOnDirectoryCsharp from './_search-on-directory-csharp.mdx'; -import SearchOnDirectoryHttp from './_search-on-directory-http.mdx'; +import SearchOnDirectoryCsharp from './content/_search-on-directory-csharp.mdx'; +import SearchOnDirectoryHttp from './content/_search-on-directory-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-overview.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-overview.mdx index b95fbba7f8..d2559b8f66 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-overview.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/search/search-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchOverviewCsharp from './_search-overview-csharp.mdx'; -import SearchOverviewHttp from './_search-overview-http.mdx'; +import SearchOverviewCsharp from './content/_search-overview-csharp.mdx'; +import SearchOverviewHttp from './content/_search-overview-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/files/upload.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/files/upload.mdx index ad33ec9bee..3fb0f86a48 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/files/upload.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/files/upload.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UploadCsharp from './_upload-csharp.mdx'; -import UploadHttp from './_upload-http.mdx'; +import UploadCsharp from './content/_upload-csharp.mdx'; +import UploadHttp from './content/_upload-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/cleanup.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/cleanup.mdx index 3f765f46b5..95064c4ab8 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/storage/cleanup.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/storage/cleanup.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CleanupCsharp from './_cleanup-csharp.mdx'; -import CleanupHttp from './_cleanup-http.mdx'; +import CleanupCsharp from './content/_cleanup-csharp.mdx'; +import CleanupHttp from './content/_cleanup-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/_cleanup-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_cleanup-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/storage/_cleanup-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_cleanup-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/_cleanup-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_cleanup-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/storage/_cleanup-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_cleanup-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/_retry-renaming-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_retry-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/storage/_retry-renaming-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_retry-renaming-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/_retry-renaming-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_retry-renaming-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/storage/_retry-renaming-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/storage/content/_retry-renaming-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/storage/retry-renaming.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/storage/retry-renaming.mdx index d1fdd6f241..329dbccfef 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/storage/retry-renaming.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/storage/retry-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetryRenamingCsharp from './_retry-renaming-csharp.mdx'; -import RetryRenamingHttp from './_retry-renaming-http.mdx'; +import RetryRenamingCsharp from './content/_retry-renaming-csharp.mdx'; +import RetryRenamingHttp from './content/_retry-renaming-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_get-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_get-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_get-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_get-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_resolve-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_resolve-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_resolve-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_resolve-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_resolve-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_resolve-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/_resolve-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/content/_resolve-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/get.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/get.mdx index a739024ad8..85be44500e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/get.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/resolve.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/resolve.mdx index 3a02cd3c7a..ef8586ac99 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/resolve.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/conflicts/resolve.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResolveCsharp from './_resolve-csharp.mdx'; -import ResolveHttp from './_resolve-http.mdx'; +import ResolveCsharp from './content/_resolve-csharp.mdx'; +import ResolveHttp from './content/_resolve-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/_start-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/content/_start-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/_start-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/content/_start-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/_start-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/content/_start-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/_start-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/content/_start-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_get-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_get-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_get-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_get-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_get-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_set-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_set-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_set-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_set-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_set-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_set-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/_set-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/content/_set-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/get.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/get.mdx index 6b6268ff59..3a8a714b8b 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/get.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/set.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/set.mdx index 35bdf80e7c..e29620fc2e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/set.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/destinations/set.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetCsharp from './_set-csharp.mdx'; -import SetHttp from './_set-http.mdx'; +import SetCsharp from './content/_set-csharp.mdx'; +import SetHttp from './content/_set-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/active.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/active.mdx index 1b8425e292..1808cd52d5 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/active.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/active.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ActiveCsharp from './_active-csharp.mdx'; -import ActiveHttp from './_active-http.mdx'; +import ActiveCsharp from './content/_active-csharp.mdx'; +import ActiveHttp from './content/_active-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_active-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_active-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_active-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_active-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_active-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_active-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_active-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_active-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_finished-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_finished-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_finished-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_finished-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_finished-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_finished-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_finished-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_finished-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_pending-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_pending-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_pending-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_pending-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_pending-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_pending-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_pending-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_pending-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_status-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_status-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_status-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_status-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_status-http.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_status-http.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/_status-http.mdx rename to versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/content/_status-http.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/finished.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/finished.mdx index f85ebf773c..87cce1bb82 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/finished.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/finished.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FinishedCsharp from './_finished-csharp.mdx'; -import FinishedHttp from './_finished-http.mdx'; +import FinishedCsharp from './content/_finished-csharp.mdx'; +import FinishedHttp from './content/_finished-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/pending.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/pending.mdx index c163bcb09e..6a9f301325 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/pending.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/pending.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PendingCsharp from './_pending-csharp.mdx'; -import PendingHttp from './_pending-http.mdx'; +import PendingCsharp from './content/_pending-csharp.mdx'; +import PendingHttp from './content/_pending-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/status.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/status.mdx index e3998c108b..7888601f1e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/status.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/monitoring/status.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StatusCsharp from './_status-csharp.mdx'; -import StatusHttp from './_status-http.mdx'; +import StatusCsharp from './content/_status-csharp.mdx'; +import StatusHttp from './content/_status-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/start.mdx b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/start.mdx index e59549e606..a4f685b3d4 100644 --- a/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/start.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/commands/synchronization/start.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartCsharp from './_start-csharp.mdx'; -import StartHttp from './_start-http.mdx'; +import StartCsharp from './content/_start-csharp.mdx'; +import StartHttp from './content/_start-http.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/conflict-listeners.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/conflict-listeners.mdx index 9989e68c41..e4dade289b 100644 --- a/versioned_docs/version-3.0/file-system/client-api/listeners/conflict-listeners.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/listeners/conflict-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictListenersCsharp from './_conflict-listeners-csharp.mdx'; +import ConflictListenersCsharp from './content/_conflict-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/_conflict-listeners-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/content/_conflict-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/listeners/_conflict-listeners-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/listeners/content/_conflict-listeners-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/_delete-listeners-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/content/_delete-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/listeners/_delete-listeners-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/listeners/content/_delete-listeners-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/_metadata-change-listeners-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/content/_metadata-change-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/listeners/_metadata-change-listeners-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/listeners/content/_metadata-change-listeners-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/_what-are-listeners-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/content/_what-are-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/listeners/_what-are-listeners-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/listeners/content/_what-are-listeners-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/delete-listeners.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/delete-listeners.mdx index 3bb78eebd4..45c5e64dd2 100644 --- a/versioned_docs/version-3.0/file-system/client-api/listeners/delete-listeners.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/listeners/delete-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteListenersCsharp from './_delete-listeners-csharp.mdx'; +import DeleteListenersCsharp from './content/_delete-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/metadata-change-listeners.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/metadata-change-listeners.mdx index 1a7e7cb0ea..a60ad9ed9d 100644 --- a/versioned_docs/version-3.0/file-system/client-api/listeners/metadata-change-listeners.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/listeners/metadata-change-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MetadataChangeListenersCsharp from './_metadata-change-listeners-csharp.mdx'; +import MetadataChangeListenersCsharp from './content/_metadata-change-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/listeners/what-are-listeners.mdx b/versioned_docs/version-3.0/file-system/client-api/listeners/what-are-listeners.mdx index 8e1cf29c80..b84b4988cd 100644 --- a/versioned_docs/version-3.0/file-system/client-api/listeners/what-are-listeners.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/listeners/what-are-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreListenersCsharp from './_what-are-listeners-csharp.mdx'; +import WhatAreListenersCsharp from './content/_what-are-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/changing-metadata.mdx b/versioned_docs/version-3.0/file-system/client-api/session/changing-metadata.mdx index 5128af61a9..556a15ad89 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/changing-metadata.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/changing-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangingMetadataCsharp from './_changing-metadata-csharp.mdx'; +import ChangingMetadataCsharp from './content/_changing-metadata-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 7de0106460..f66af9eeb1 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 5b9072b439..68f2c78859 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_changing-metadata-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_changing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_changing-metadata-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_changing-metadata-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_deleting-files-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_deleting-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_deleting-files-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_deleting-files-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_downloading-files-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_downloading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_downloading-files-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_downloading-files-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_loading-files-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_loading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_loading-files-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_loading-files-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_opening-session-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_opening-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_opening-session-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_opening-session-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_renaming-files-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_renaming-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_renaming-files-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_renaming-files-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/_uploading-files-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/content/_uploading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/_uploading-files-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/content/_uploading-files-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/deleting-files.mdx b/versioned_docs/version-3.0/file-system/client-api/session/deleting-files.mdx index 064efea10f..3a052692a7 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/deleting-files.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/deleting-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingFilesCsharp from './_deleting-files-csharp.mdx'; +import DeletingFilesCsharp from './content/_deleting-files-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/downloading-files.mdx b/versioned_docs/version-3.0/file-system/client-api/session/downloading-files.mdx index d5c3eff227..8fd942a1d5 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/downloading-files.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/downloading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DownloadingFilesCsharp from './_downloading-files-csharp.mdx'; +import DownloadingFilesCsharp from './content/_downloading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/loading-files.mdx b/versioned_docs/version-3.0/file-system/client-api/session/loading-files.mdx index 272febc243..a04fa34057 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/loading-files.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/loading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingFilesCsharp from './_loading-files-csharp.mdx'; +import LoadingFilesCsharp from './content/_loading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/opening-session.mdx b/versioned_docs/version-3.0/file-system/client-api/session/opening-session.mdx index 403c39250b..b94277df52 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/opening-session.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/opening-session.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningSessionCsharp from './_opening-session-csharp.mdx'; +import OpeningSessionCsharp from './content/_opening-session-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/basics.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/basics.mdx index cbf2f57cef..48c22818d3 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/querying/basics.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/querying/basics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/_basics-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/querying/_basics-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/_filtering-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/querying/_filtering-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/_paging-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/content/_paging-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/querying/_paging-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/querying/content/_paging-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/_sorting-csharp.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/file-system/client-api/session/querying/_sorting-csharp.mdx rename to versioned_docs/version-3.0/file-system/client-api/session/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/filtering.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/filtering.mdx index df25fac6b5..b7aa321a46 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/querying/filtering.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/querying/filtering.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/paging.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/paging.mdx index a064254d94..03776c36ab 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/querying/paging.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/querying/paging.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/querying/sorting.mdx b/versioned_docs/version-3.0/file-system/client-api/session/querying/sorting.mdx index bfe3b5ddf8..031f5338ad 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/querying/sorting.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/querying/sorting.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/renaming-files.mdx b/versioned_docs/version-3.0/file-system/client-api/session/renaming-files.mdx index 0f3f6d240f..e51ed2952e 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/renaming-files.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/renaming-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RenamingFilesCsharp from './_renaming-files-csharp.mdx'; +import RenamingFilesCsharp from './content/_renaming-files-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/saving-changes.mdx b/versioned_docs/version-3.0/file-system/client-api/session/saving-changes.mdx index c3b7ed58d6..2e0e213b48 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/saving-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.0/file-system/client-api/session/uploading-files.mdx b/versioned_docs/version-3.0/file-system/client-api/session/uploading-files.mdx index 628848ccd4..88c0d52694 100644 --- a/versioned_docs/version-3.0/file-system/client-api/session/uploading-files.mdx +++ b/versioned_docs/version-3.0/file-system/client-api/session/uploading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UploadingFilesCsharp from './_uploading-files-csharp.mdx'; +import UploadingFilesCsharp from './content/_uploading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21eee7fbfe..0000000000 --- a/versioned_docs/version-3.0/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -To achieve this in RavenDB, let's say you have a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against, this can be setup like so: - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Next you need to setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field look at the documents and return a count for each unique Term found -* For the **Cost** field, return the count of the following ranges: - * Cost <= 200.0 - * 200.0 <= Cost <= 400.0 - * 400.0 <= Cost <= 600.0 - * 600.0 <= Cost <= 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels <= 7.0 - * 7.0 <= Megapixels <= 10.0 - * Megapixels >= 10.0 - -## Step 3 - -Finally you can write the following code and you get back the data below: - - - - -{`FacetResults facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .ToFacets(facets); -`} - - - - -{`FacetResults facetResults = session - .Advanced - .DocumentQuery() - .WhereBetweenOrEqual(x => x.Cost, 100, 300) - .ToFacets(facets); -`} - - - - -{`FacetResults facetResults = store - .DatabaseCommands - .GetFacets( - "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery - { - Query = "Cost_Range:[Dx100 TO Dx300]" - }, - facets); -`} - - - - -{`List facets = new List -{ - new Facet - { - Name = "Manufacturer" - }, - new Facet - { - Name = x => x.Cost, - Ranges = - { - x => x.Cost < 200m, - x => x.Cost > 200m && x.Cost < 400m, - x => x.Cost > 400m && x.Cost < 600m, - x => x.Cost > 600m && x.Cost < 800m, - x => x.Cost > 800m - } - }, - new Facet - { - Name = x => x.Megapixels, - Ranges = - { - x => x.Megapixels < 3.0, - x => x.Megapixels > 3.0 && x.Megapixels < 7.0, - x => x.Megapixels > 7.0 && x.Megapixels < 10.0, - x => x.Megapixels > 10.0 - } - } -}; -`} - - - - -The data below represents the sample faceted data that satisfies above query: - - - -{`\{ - Manufacturer: [ - \{ - Range: 'canon', - Count: 42 - \}, - \{ - Range: 'jessops', - Count: 50 - \}, - \{ - Range: 'nikon', - Count: 46 - \}, - \{ - Range: 'phillips', - Count: 44 - \}, - \{ - Range: 'sony', - Count: 35 - \} - ], - Cost_Range: [ - \{ - Range: '[NULL TO Dx200.0]', - Count: 115 - \}, - \{ - Range: '[Dx200.0 TO Dx400.0]', - Count: 102 - \} - ], - Megapixels_Range: [ - \{ - Range: '[NULL TO Dx3.0]', - Count: 42 - \}, - \{ - Range: '[Dx3.0 TO Dx7.0]', - Count: 79 - \}, - \{ - Range: '[Dx7.0 TO Dx10.0]', - Count: 82 - \}, - \{ - Range: '[Dx10.0 TO NULL]', - Count: 14 - \} - ] -\} -`} - - - -### Storing facets - -Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`FacetResults facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .ToFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = session - .Advanced - .DocumentQuery() - .WhereBetweenOrEqual(x => x.Cost, 100, 300) - .ToFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = store - .DatabaseCommands - .GetFacets( - "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery - { - Query = "Cost_Range:[Dx100 TO Dx300]" - }, - "facets/CameraFacets"); -`} - - - - -{`List facets = new List -{ - new Facet - { - Name = "Manufacturer" - }, - new Facet - { - Name = x => x.Cost, - Ranges = - { - x => x.Cost < 200m, - x => x.Cost > 200m && x.Cost < 400m, - x => x.Cost > 400m && x.Cost < 600m, - x => x.Cost > 600m && x.Cost < 800m, - x => x.Cost > 800m - } - }, - new Facet - { - Name = x => x.Megapixels, - Ranges = - { - x => x.Megapixels < 3.0, - x => x.Megapixels > 3.0 && x.Megapixels < 7.0, - x => x.Megapixels > 7.0 && x.Megapixels < 10.0, - x => x.Megapixels > 10.0 - } - } -}; -`} - - - - -### Stale results - -The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `WaitForNonStaleResultsXXX` method. - - diff --git a/versioned_docs/version-3.0/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-3.0/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index b38c2e733a..0000000000 --- a/versioned_docs/version-3.0/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -To achieve this in RavenDB, let's say you have a document like this: - - - -{`public class Camera \{ - private int id; - - private Date dateOfListing; - private String manufacturer; - private String model; - private Double cost; - - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private List advancedFeatures; - - public int getId() \{ - return id; - \} - public void setId(int id) \{ - this.id = id; - \} - public Date getDateOfListing() \{ - return dateOfListing; - \} - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - public String getManufacturer() \{ - return manufacturer; - \} - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} - public String getModel() \{ - return model; - \} - public void setModel(String model) \{ - this.model = model; - \} - public Double getCost() \{ - return cost; - \} - public void setCost(Double cost) \{ - this.cost = cost; - \} - public int getZoom() \{ - return zoom; - \} - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - public double getMegapixels() \{ - return megapixels; - \} - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - public List getAdvancedFeatures() \{ - return advancedFeatures; - \} - public void setAdvancedFeatures(List advancedFeatures) \{ - this.advancedFeatures = advancedFeatures; - \} -\} -`} - - - -## Step 1 - -Create an index to work against, this can be setup like so: - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Next you need to setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field look at the documents and return a count for each unique Term found -* For the **Cost** field, return the count of the following ranges: - * Cost <= 200.0 - * 200.0 <= Cost <= 400.0 - * 400.0 <= Cost <= 600.0 - * 600.0 <= Cost <= 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels <= 7.0 - * 7.0 <= Megapixels <= 10.0 - * Megapixels >= 10.0 - -## Step 3 - -Finally you can write the following code and you get back the data below: - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .where(c.cost.goe(100).and(c.cost.loe(300))) - .toFacets(facets); -`} - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .advanced() - .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetweenOrEqual(c.cost, 100.0, 300.0) - .toFacets(facets); -`} - - - - -{`FacetResults facetResults = store - .getDatabaseCommands() - .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), - facets); -`} - - - - -{`QCamera c = QCamera.camera; - -List facets = new ArrayList<>(); -Facet f1 = new Facet(); -f1.setName(c.manufacturer); -facets.add(f1); - -Facet f2 = new Facet(); -f2.setName(c.cost); -f2.setRanges(c.cost.lt(200), - c.cost.gt(200).and(c.cost.lt(400)), - c.cost.gt(400).and(c.cost.lt(600)), - c.cost.gt(600).and(c.cost.lt(800)), - c.cost.gt(800)); -facets.add(f2); - -Facet f3 = new Facet(); -f3.setName(c.megapixels); -f3.setRanges(c.megapixels.lt(3), - c.megapixels.gt(3).and(c.megapixels.lt(7)), - c.megapixels.gt(7).and(c.megapixels.lt(10)), - c.megapixels.gt(10)); -facets.add(f3); -`} - - - - -The data below represents the sample faceted data that satisfies above query: - - - -{`\{ - Manufacturer: [ - \{ - Range: 'canon', - Count: 42 - \}, - \{ - Range: 'jessops', - Count: 50 - \}, - \{ - Range: 'nikon', - Count: 46 - \}, - \{ - Range: 'phillips', - Count: 44 - \}, - \{ - Range: 'sony', - Count: 35 - \} - ], - Cost_Range: [ - \{ - Range: '[NULL TO Dx200.0]', - Count: 115 - \}, - \{ - Range: '[Dx200.0 TO Dx400.0]', - Count: 102 - \} - ], - Megapixels_Range: [ - \{ - Range: '[NULL TO Dx3.0]', - Count: 42 - \}, - \{ - Range: '[Dx3.0 TO Dx7.0]', - Count: 79 - \}, - \{ - Range: '[Dx7.0 TO Dx10.0]', - Count: 82 - \}, - \{ - Range: '[Dx10.0 TO NULL]', - Count: 14 - \} - ] -\} -`} - - - -### Storing facets - -Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .where(c.cost.goe(100).and(c.cost.loe(300))) - .toFacets("facets/CameraFacets"); -`} - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .advanced() - .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetweenOrEqual(c.cost, 100.0, 300.0) - .toFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = store - .getDatabaseCommands() - .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), - "facets/CameraFacets"); -`} - - - - -{`QCamera c = QCamera.camera; - -List facets = new ArrayList<>(); -Facet f1 = new Facet(); -f1.setName(c.manufacturer); -facets.add(f1); - -Facet f2 = new Facet(); -f2.setName(c.cost); -f2.setRanges(c.cost.lt(200), - c.cost.gt(200).and(c.cost.lt(400)), - c.cost.gt(400).and(c.cost.lt(600)), - c.cost.gt(600).and(c.cost.lt(800)), - c.cost.gt(800)); -facets.add(f2); - -Facet f3 = new Facet(); -f3.setName(c.megapixels); -f3.setRanges(c.megapixels.lt(3), - c.megapixels.gt(3).and(c.megapixels.lt(7)), - c.megapixels.gt(7).and(c.megapixels.lt(10)), - c.megapixels.gt(10)); -facets.add(f3); -`} - - - - -### Stale results - -The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `waitForNonStaleResultsXXX` method. - - diff --git a/versioned_docs/version-3.0/indexes/querying/basics.mdx b/versioned_docs/version-3.0/indexes/querying/basics.mdx index 4a6522b0f9..42cfb4ad1a 100644 --- a/versioned_docs/version-3.0/indexes/querying/basics.mdx +++ b/versioned_docs/version-3.0/indexes/querying/basics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_basics-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_basics-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_dynamic-aggregation-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_dynamic-aggregation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_dynamic-aggregation-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_dynamic-aggregation-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_dynamic-aggregation-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_dynamic-aggregation-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_dynamic-aggregation-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_dynamic-aggregation-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..a5b7c793dd --- /dev/null +++ b/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +To achieve this in RavenDB, let's say you have a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against, this can be setup like so: + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Next you need to setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field look at the documents and return a count for each unique Term found +* For the **Cost** field, return the count of the following ranges: + * Cost <= 200.0 + * 200.0 <= Cost <= 400.0 + * 400.0 <= Cost <= 600.0 + * 600.0 <= Cost <= 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels <= 7.0 + * 7.0 <= Megapixels <= 10.0 + * Megapixels >= 10.0 + +## Step 3 + +Finally you can write the following code and you get back the data below: + + + + +{`FacetResults facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .ToFacets(facets); +`} + + + + +{`FacetResults facetResults = session + .Advanced + .DocumentQuery() + .WhereBetweenOrEqual(x => x.Cost, 100, 300) + .ToFacets(facets); +`} + + + + +{`FacetResults facetResults = store + .DatabaseCommands + .GetFacets( + "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery + { + Query = "Cost_Range:[Dx100 TO Dx300]" + }, + facets); +`} + + + + +{`List facets = new List +{ + new Facet + { + Name = "Manufacturer" + }, + new Facet + { + Name = x => x.Cost, + Ranges = + { + x => x.Cost < 200m, + x => x.Cost > 200m && x.Cost < 400m, + x => x.Cost > 400m && x.Cost < 600m, + x => x.Cost > 600m && x.Cost < 800m, + x => x.Cost > 800m + } + }, + new Facet + { + Name = x => x.Megapixels, + Ranges = + { + x => x.Megapixels < 3.0, + x => x.Megapixels > 3.0 && x.Megapixels < 7.0, + x => x.Megapixels > 7.0 && x.Megapixels < 10.0, + x => x.Megapixels > 10.0 + } + } +}; +`} + + + + +The data below represents the sample faceted data that satisfies above query: + + + +{`\{ + Manufacturer: [ + \{ + Range: 'canon', + Count: 42 + \}, + \{ + Range: 'jessops', + Count: 50 + \}, + \{ + Range: 'nikon', + Count: 46 + \}, + \{ + Range: 'phillips', + Count: 44 + \}, + \{ + Range: 'sony', + Count: 35 + \} + ], + Cost_Range: [ + \{ + Range: '[NULL TO Dx200.0]', + Count: 115 + \}, + \{ + Range: '[Dx200.0 TO Dx400.0]', + Count: 102 + \} + ], + Megapixels_Range: [ + \{ + Range: '[NULL TO Dx3.0]', + Count: 42 + \}, + \{ + Range: '[Dx3.0 TO Dx7.0]', + Count: 79 + \}, + \{ + Range: '[Dx7.0 TO Dx10.0]', + Count: 82 + \}, + \{ + Range: '[Dx10.0 TO NULL]', + Count: 14 + \} + ] +\} +`} + + + +### Storing facets + +Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`FacetResults facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .ToFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = session + .Advanced + .DocumentQuery() + .WhereBetweenOrEqual(x => x.Cost, 100, 300) + .ToFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = store + .DatabaseCommands + .GetFacets( + "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery + { + Query = "Cost_Range:[Dx100 TO Dx300]" + }, + "facets/CameraFacets"); +`} + + + + +{`List facets = new List +{ + new Facet + { + Name = "Manufacturer" + }, + new Facet + { + Name = x => x.Cost, + Ranges = + { + x => x.Cost < 200m, + x => x.Cost > 200m && x.Cost < 400m, + x => x.Cost > 400m && x.Cost < 600m, + x => x.Cost > 600m && x.Cost < 800m, + x => x.Cost > 800m + } + }, + new Facet + { + Name = x => x.Megapixels, + Ranges = + { + x => x.Megapixels < 3.0, + x => x.Megapixels > 3.0 && x.Megapixels < 7.0, + x => x.Megapixels > 7.0 && x.Megapixels < 10.0, + x => x.Megapixels > 10.0 + } + } +}; +`} + + + + +### Stale results + +The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `WaitForNonStaleResultsXXX` method. + + diff --git a/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..bffd887b33 --- /dev/null +++ b/versioned_docs/version-3.0/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +To achieve this in RavenDB, let's say you have a document like this: + + + +{`public class Camera \{ + private int id; + + private Date dateOfListing; + private String manufacturer; + private String model; + private Double cost; + + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private List advancedFeatures; + + public int getId() \{ + return id; + \} + public void setId(int id) \{ + this.id = id; + \} + public Date getDateOfListing() \{ + return dateOfListing; + \} + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + public String getManufacturer() \{ + return manufacturer; + \} + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} + public String getModel() \{ + return model; + \} + public void setModel(String model) \{ + this.model = model; + \} + public Double getCost() \{ + return cost; + \} + public void setCost(Double cost) \{ + this.cost = cost; + \} + public int getZoom() \{ + return zoom; + \} + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + public double getMegapixels() \{ + return megapixels; + \} + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + public List getAdvancedFeatures() \{ + return advancedFeatures; + \} + public void setAdvancedFeatures(List advancedFeatures) \{ + this.advancedFeatures = advancedFeatures; + \} +\} +`} + + + +## Step 1 + +Create an index to work against, this can be setup like so: + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Next you need to setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field look at the documents and return a count for each unique Term found +* For the **Cost** field, return the count of the following ranges: + * Cost <= 200.0 + * 200.0 <= Cost <= 400.0 + * 400.0 <= Cost <= 600.0 + * 600.0 <= Cost <= 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels <= 7.0 + * 7.0 <= Megapixels <= 10.0 + * Megapixels >= 10.0 + +## Step 3 + +Finally you can write the following code and you get back the data below: + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .where(c.cost.goe(100).and(c.cost.loe(300))) + .toFacets(facets); +`} + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .advanced() + .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetweenOrEqual(c.cost, 100.0, 300.0) + .toFacets(facets); +`} + + + + +{`FacetResults facetResults = store + .getDatabaseCommands() + .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), + facets); +`} + + + + +{`QCamera c = QCamera.camera; + +List facets = new ArrayList<>(); +Facet f1 = new Facet(); +f1.setName(c.manufacturer); +facets.add(f1); + +Facet f2 = new Facet(); +f2.setName(c.cost); +f2.setRanges(c.cost.lt(200), + c.cost.gt(200).and(c.cost.lt(400)), + c.cost.gt(400).and(c.cost.lt(600)), + c.cost.gt(600).and(c.cost.lt(800)), + c.cost.gt(800)); +facets.add(f2); + +Facet f3 = new Facet(); +f3.setName(c.megapixels); +f3.setRanges(c.megapixels.lt(3), + c.megapixels.gt(3).and(c.megapixels.lt(7)), + c.megapixels.gt(7).and(c.megapixels.lt(10)), + c.megapixels.gt(10)); +facets.add(f3); +`} + + + + +The data below represents the sample faceted data that satisfies above query: + + + +{`\{ + Manufacturer: [ + \{ + Range: 'canon', + Count: 42 + \}, + \{ + Range: 'jessops', + Count: 50 + \}, + \{ + Range: 'nikon', + Count: 46 + \}, + \{ + Range: 'phillips', + Count: 44 + \}, + \{ + Range: 'sony', + Count: 35 + \} + ], + Cost_Range: [ + \{ + Range: '[NULL TO Dx200.0]', + Count: 115 + \}, + \{ + Range: '[Dx200.0 TO Dx400.0]', + Count: 102 + \} + ], + Megapixels_Range: [ + \{ + Range: '[NULL TO Dx3.0]', + Count: 42 + \}, + \{ + Range: '[Dx3.0 TO Dx7.0]', + Count: 79 + \}, + \{ + Range: '[Dx7.0 TO Dx10.0]', + Count: 82 + \}, + \{ + Range: '[Dx10.0 TO NULL]', + Count: 14 + \} + ] +\} +`} + + + +### Storing facets + +Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .where(c.cost.goe(100).and(c.cost.loe(300))) + .toFacets("facets/CameraFacets"); +`} + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .advanced() + .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetweenOrEqual(c.cost, 100.0, 300.0) + .toFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = store + .getDatabaseCommands() + .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), + "facets/CameraFacets"); +`} + + + + +{`QCamera c = QCamera.camera; + +List facets = new ArrayList<>(); +Facet f1 = new Facet(); +f1.setName(c.manufacturer); +facets.add(f1); + +Facet f2 = new Facet(); +f2.setName(c.cost); +f2.setRanges(c.cost.lt(200), + c.cost.gt(200).and(c.cost.lt(400)), + c.cost.gt(400).and(c.cost.lt(600)), + c.cost.gt(600).and(c.cost.lt(800)), + c.cost.gt(800)); +facets.add(f2); + +Facet f3 = new Facet(); +f3.setName(c.megapixels); +f3.setRanges(c.megapixels.lt(3), + c.megapixels.gt(3).and(c.megapixels.lt(7)), + c.megapixels.gt(7).and(c.megapixels.lt(10)), + c.megapixels.gt(10)); +facets.add(f3); +`} + + + + +### Stale results + +The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `waitForNonStaleResultsXXX` method. + + diff --git a/versioned_docs/version-3.0/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_filtering-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_handling-document-relationships-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_handling-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_handling-document-relationships-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_handling-document-relationships-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_handling-document-relationships-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_handling-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_handling-document-relationships-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_handling-document-relationships-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_highlights-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_highlights-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_highlights-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_highlights-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_highlights-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_highlights-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_highlights-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_highlights-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_intersection-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_paging-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_paging-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_paging-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_paging-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_paging-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_paging-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_paging-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_projections-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_projections-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_searching-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_searching-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_sorting-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_spatial-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_spatial-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_spatial-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_spatial-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-3.0/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-3.0/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.0/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-3.0/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-3.0/indexes/querying/dynamic-aggregation.mdx b/versioned_docs/version-3.0/indexes/querying/dynamic-aggregation.mdx index 7daf0c8130..ef3234d8df 100644 --- a/versioned_docs/version-3.0/indexes/querying/dynamic-aggregation.mdx +++ b/versioned_docs/version-3.0/indexes/querying/dynamic-aggregation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DynamicAggregationCsharp from './_dynamic-aggregation-csharp.mdx'; -import DynamicAggregationJava from './_dynamic-aggregation-java.mdx'; +import DynamicAggregationCsharp from './content/_dynamic-aggregation-csharp.mdx'; +import DynamicAggregationJava from './content/_dynamic-aggregation-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/faceted-search.mdx b/versioned_docs/version-3.0/indexes/querying/faceted-search.mdx index 6e917cb1ea..db769634cd 100644 --- a/versioned_docs/version-3.0/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-3.0/indexes/querying/faceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/filtering.mdx b/versioned_docs/version-3.0/indexes/querying/filtering.mdx index f95e602be8..f5ad6033bf 100644 --- a/versioned_docs/version-3.0/indexes/querying/filtering.mdx +++ b/versioned_docs/version-3.0/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/handling-document-relationships.mdx b/versioned_docs/version-3.0/indexes/querying/handling-document-relationships.mdx index 196dd9ec93..d90ac2d3fa 100644 --- a/versioned_docs/version-3.0/indexes/querying/handling-document-relationships.mdx +++ b/versioned_docs/version-3.0/indexes/querying/handling-document-relationships.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandlingDocumentRelationshipsCsharp from './_handling-document-relationships-csharp.mdx'; -import HandlingDocumentRelationshipsJava from './_handling-document-relationships-java.mdx'; +import HandlingDocumentRelationshipsCsharp from './content/_handling-document-relationships-csharp.mdx'; +import HandlingDocumentRelationshipsJava from './content/_handling-document-relationships-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/highlights.mdx b/versioned_docs/version-3.0/indexes/querying/highlights.mdx index b3d4f4c276..9bbaea6e2d 100644 --- a/versioned_docs/version-3.0/indexes/querying/highlights.mdx +++ b/versioned_docs/version-3.0/indexes/querying/highlights.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightsCsharp from './_highlights-csharp.mdx'; -import HighlightsJava from './_highlights-java.mdx'; +import HighlightsCsharp from './content/_highlights-csharp.mdx'; +import HighlightsJava from './content/_highlights-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/intersection.mdx b/versioned_docs/version-3.0/indexes/querying/intersection.mdx index 0d06d9311a..742ca9b295 100644 --- a/versioned_docs/version-3.0/indexes/querying/intersection.mdx +++ b/versioned_docs/version-3.0/indexes/querying/intersection.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/paging.mdx b/versioned_docs/version-3.0/indexes/querying/paging.mdx index 87bdf3226d..e813030ad5 100644 --- a/versioned_docs/version-3.0/indexes/querying/paging.mdx +++ b/versioned_docs/version-3.0/indexes/querying/paging.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/projections.mdx b/versioned_docs/version-3.0/indexes/querying/projections.mdx index 1c2d7ed365..f01c2dd0d5 100644 --- a/versioned_docs/version-3.0/indexes/querying/projections.mdx +++ b/versioned_docs/version-3.0/indexes/querying/projections.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-3.0/indexes/querying/query-vs-document-query.mdx index ffc799c354..8bb7c5e751 100644 --- a/versioned_docs/version-3.0/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-3.0/indexes/querying/query-vs-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/searching.mdx b/versioned_docs/version-3.0/indexes/querying/searching.mdx index 3f38918857..5918d72a38 100644 --- a/versioned_docs/version-3.0/indexes/querying/searching.mdx +++ b/versioned_docs/version-3.0/indexes/querying/searching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/sorting.mdx b/versioned_docs/version-3.0/indexes/querying/sorting.mdx index 9ad7e60838..8172ba7af0 100644 --- a/versioned_docs/version-3.0/indexes/querying/sorting.mdx +++ b/versioned_docs/version-3.0/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/spatial.mdx b/versioned_docs/version-3.0/indexes/querying/spatial.mdx index 40ee49a4ed..81fe740983 100644 --- a/versioned_docs/version-3.0/indexes/querying/spatial.mdx +++ b/versioned_docs/version-3.0/indexes/querying/spatial.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-3.0/indexes/querying/suggestions.mdx b/versioned_docs/version-3.0/indexes/querying/suggestions.mdx index 698c8a7591..391158b55a 100644 --- a/versioned_docs/version-3.0/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-3.0/indexes/querying/suggestions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; diff --git a/versioned_docs/version-3.0/start/_getting-started-csharp.mdx b/versioned_docs/version-3.0/start/content/_getting-started-csharp.mdx similarity index 100% rename from versioned_docs/version-3.0/start/_getting-started-csharp.mdx rename to versioned_docs/version-3.0/start/content/_getting-started-csharp.mdx diff --git a/versioned_docs/version-3.0/start/_getting-started-java.mdx b/versioned_docs/version-3.0/start/content/_getting-started-java.mdx similarity index 100% rename from versioned_docs/version-3.0/start/_getting-started-java.mdx rename to versioned_docs/version-3.0/start/content/_getting-started-java.mdx diff --git a/versioned_docs/version-3.0/start/getting-started.mdx b/versioned_docs/version-3.0/start/getting-started.mdx index 1bb9f31ea4..80e5cdab14 100644 --- a/versioned_docs/version-3.0/start/getting-started.mdx +++ b/versioned_docs/version-3.0/start/getting-started.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GettingStartedCsharp from './_getting-started-csharp.mdx'; -import GettingStartedJava from './_getting-started-java.mdx'; +import GettingStartedCsharp from './content/_getting-started-csharp.mdx'; +import GettingStartedJava from './content/_getting-started-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-3.5/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-3.5/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-3.5/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-3.5/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-3.5/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-3.5/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 0a7e64adb2..cc27d6a420 100644 --- a/versioned_docs/version-3.5/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-3.5/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx b/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx deleted file mode 100644 index 16fab8ea2b..0000000000 --- a/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-csharp.mdx +++ /dev/null @@ -1,284 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. - -## **Failover behavior** - - By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: - -* Detecting that an instance is replicating to another set of instances. -* When that instance is down, the client will be automatically shifted to other instances. - -This is caused by a failover mechanism which is turned in a document stored by default. The client can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. - - -The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. - - -You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option - - - -{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; -`} - - - -When `FailImmediately` option is used then client will raise exception when primary server is down. - -The remaining values of `FailoverBehavior` enumeration are: - -* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) -* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) -* *AllowReadFromSecondariesWhenRequestTimeSlaThresholdIsReached* - Allow read from secondaries when request time [SLA](../../server/scaling-out/sla.mdx) threshold is reached (configurable in conventions). -* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master - -They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. - - - -FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: - - - -{`store.Conventions.FailoverBehavior = FailoverBehavior.ReadFromAllServers - | FailoverBehavior.AllowReadsFromSecondariesAndWritesToSecondaries; -`} - - - - - - - -## **Cluster failover behavior** - -Inside the cluster by default replication bundles in all the servers are enabled. This includes: - -* All instances will be replicated to every server inside the cluster. -* Default failover behavior is `FailoverBehavior.ReadFromLeaderWriteToLeader`. -* Write calls are always referred to the leader (if a write request is made to a none leader server the client will be redirected) -* In the cluster there will be only one leader. In a case the leader is down, a vote will be made to choose another. - -To change a behavior from the client, one can use: - - -{`session.Store(new ReplicationDocument -\{ - ClientConfiguration = new ReplicationClientConfiguration - \{ - FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader - \} - -\}, "Raven/Replication/Destinations"); -`} - - - -The client can load the cluster toplogy from `/cluster/topology` to learn which servers are in the cluster and can be promoted to leader. - -You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option - - - -{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; -`} - - - -When `FailImmediately` option is used then client will raise exception when primary server is down. - -The remaining values of `FailoverBehavior` enumeration are: - -* *ReadFromLeaderWriteToLeader* (default) - Allows read from leader and write only to leader -* *ReadFromAllWriteToLeader* - Allows read from any server and write only to leader -* *ReadFromAllWriteToLeaderWithFailovers* - Allows read from leader and write only to leader with failovers. -* *ReadFromLeaderWriteToLeaderWithFailovers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master - - -The behaviors `ReadFromAllWriteToLeaderWithFailovers` and `ReadFromLeaderWriteToLeaderWithFailovers` will make the client use the new leader only when trying to write -to a unreachable server. Work only if we configure the Client failover behaviour in the server side to Let client decide . - -![Setting up let client decide on server](./assets/replication-client-configuration-let-client-decide.png) - - - - - - -## **Discovering destinations** - -Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. - -Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. - - - -## **Failover servers** - - -If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. - - -### Setup - - - -{`store.FailoverServers = new FailoverServers(); -store.FailoverServers.ForDefaultDatabase = new[] -\{ - new ReplicationDestination - \{ - Url = "http://localhost:8078", - ApiKey = "apikey" - \}, - new ReplicationDestination - \{ - Url = "http://localhost:8077/", - Database = "test", - Username = "user", - Password = "secret" - \} -\}; - -store.FailoverServers.ForDatabases = new Dictionary -\{ - \{ - "Northwind", - new[] - \{ - new ReplicationDestination - \{ - Url = "http://localhost:8076" - \} - \} - \} -\}; -`} - - - -### Setup using connection string - -To setup a failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use the `Failover` option. Multiple failovers can be setup using multiple `Failover` options. - -Failover -: Type: string in predefined format -: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` -Failover server definition. - -Example: - - - -{`session.Store(new ReplicationDocument -\{ - ClientConfiguration = new ReplicationClientConfiguration - \{ - FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader - \} - -\}, "Raven/Replication/Destinations"); -`} - - - -Full example: - - - -{` - - -`} - - - - - -## **Setting up default client configuration on server** - -Default client configuration can be 'injected' into a client, by filling out the `ClientConfiguration` property in `Raven/Replication/Destinations`. - -The available options are: - -- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. - -Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. - -![Setting up default client configuration on server](./assets/replication-client-configuration.png) - - - -## **Request redirection** - -The Raven Client API is quite intelligent in this regard, as upon failure it will: - -* Assume that the failure is transient, and retry the request, -* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, -* After ten consecutive failures, Raven will start replicating to this node less often - * Once every 10 requests, until failure count reaches 100 - * Once every 100 requests, until failure count reaches 1,000 - * Once every 1,000 requests, when failure count is above 1,000 -* On the first successful request, the failure count is reset. - -If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. - - - -## **Back to primary** - -The client shifted to a replicated node will go back to its primary server -as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. - - - -## **Replicated operations** - -At a lower level, the following operations support replication: - -* Get - single document and multi documents -* Put -* Delete -* Query -* Rollback -* Commit - -The following operations do not support replication in the Client API: - -* PutIndex -* DeleteIndex - - - -## **Custom document ID generation** - -The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids). -However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect -against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: - - - -{`store - .DatabaseCommands - .Put( -verPrefixForHilo", - null, -Object - \{ -rPrefix", "NorthServer/" \} - \}, -Object()); -`} - - - -The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. -For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. - - - - diff --git a/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx b/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx deleted file mode 100644 index ecc950ab75..0000000000 --- a/versioned_docs/version-3.5/client-api/bundles/_how-client-integrates-with-replication-bundle-java.mdx +++ /dev/null @@ -1,207 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. - -## **Failover behavior** - - By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: - -* Detecting that an instance is replicating to another set of instances. -* When that instance is down, the client will be automatically shifted to other instances. - -This is caused by a failover mechanism which is turned in a document stored by default. The clinet can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. - - -The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. - - -You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option: - - - -{`store.getConventions().setFailoverBehavior(FailoverBehaviorSet.of(FailoverBehavior.FAIL_IMMEDIATELY)); -`} - - - -When `FailImmediately` option is used then client will raise exception when primary server is down. - -The remaining values of `FailoverBehavior` enumeration are: - -* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) -* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) -* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master - -They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. - - - -FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: - - - -{`store.getConventions().setFailoverBehavior( - FailoverBehaviorSet.of( - FailoverBehavior.READ_FROM_ALL_SERVERS, - FailoverBehavior.ALLOW_READS_FROM_SECONDARIES_AND_WRITES_TO_SECONDARIES)); -`} - - - - - - - -## **Discovering destinations** - -Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. - -Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. - - - -## **Failover servers** - -If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. - -### Setup - - - -{`store.setFailoverServers(new FailoverServers()); -ReplicationDestination destination1 = new ReplicationDestination(); -destination1.setUrl("http://localhost:8078"); -destination1.setApiKey("apikey"); - -ReplicationDestination destination2 = new ReplicationDestination(); -destination2.setUrl("http://localhost:8077"); -destination2.setDatabase("test"); -destination2.setUsername("user"); -destination2.setPassword("secret"); -store.getFailoverServers().addForDefaultDatabase(destination1, destination2); - -ReplicationDestination northwindDestination = new ReplicationDestination(); -northwindDestination.setUrl("http://localhost:8076"); - -store.getFailoverServers().addForDatabase("Northwind", northwindDestination); -`} - - - -### Setup using connection string - -To setup failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use `Failover` option. Multiple failovers can be setup using multiple `Failover` options. - -Failover -: Type: string in predefined format -: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` -Failover server definition. - -Example: - - - -{`Url = http://localhost:59233; - // Primary server url -Failover = \{ Url:'http://localhost:8078'\}; - // Failover for DefaultDatabase -Failover = \{ Url:'http://localhost:8077/', Database:'test'\}; - // Failover for DefaultDatabase with non-default database -Failover = Northwind|\{ Url:'http://localhost:8076/'\}; - // Failover for 'Northwind' database -Failover= \{ Url:'http://localhost:8075', Username:'user', Password:'secret'\}; - // Failover for DefaultDatabase with Username and Password -Failover= \{ Url:'http://localhost:8074', ApiKey:'d5723e19-92ad-4531-adad-8611e6e05c8a'\} - // Failover for DefaultDatabase with ApiKey -`} - - - - - -## **Setting up default client configuration on server** - -Default client configuration can be 'injected' into client, by filling out `ClientConfiguration` property in `Raven/Replication/Destinations`. - -The available options are: - -- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. - -Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. - -![Setting up default client configuration on server](./assets/replication-client-configuration.png) - - - -## **Request redirection** - -The Raven Client API is quite intelligent in this regard, as upon failure it will: - -* Assume that the failure is transient, and retry the request, -* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, -* After ten consecutive failures, Raven will start replicating to this node less often - * Once every 10 requests, until failure count reaches 100 - * Once every 100 requests, until failure count reaches 1,000 - * Once every 1,000 requests, when failure count is above 1,000 -* On the first successful request, the failure count is reset. - -If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. - - - -## **Back to primary** - -The client shifted to a replicated node will go back to its primary server -as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. - - - -## **Replicated operations** - -At a lower level, the following operations support replication: - -* Get - single document and multi documents -* Put -* Delete -* Query -* Rollback -* Commit - -The following operations do not support replication in the Client API: - -* PutIndex -* DeleteIndex - - - -## **Custom document ID generation** - -The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids) -However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect -against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: - - - -{`store - .DatabaseCommands - .Put( -verPrefixForHilo", - null, -Object - \{ -rPrefix", "NorthServer/" \} - \}, -Object()); -`} - - - -The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. -For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. - - - - diff --git a/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx b/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx new file mode 100644 index 0000000000..df3b1ec5a7 --- /dev/null +++ b/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-csharp.mdx @@ -0,0 +1,284 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. + +## **Failover behavior** + + By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: + +* Detecting that an instance is replicating to another set of instances. +* When that instance is down, the client will be automatically shifted to other instances. + +This is caused by a failover mechanism which is turned in a document stored by default. The client can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. + + +The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. + + +You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option + + + +{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; +`} + + + +When `FailImmediately` option is used then client will raise exception when primary server is down. + +The remaining values of `FailoverBehavior` enumeration are: + +* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) +* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) +* *AllowReadFromSecondariesWhenRequestTimeSlaThresholdIsReached* - Allow read from secondaries when request time [SLA](../../server/scaling-out/sla.mdx) threshold is reached (configurable in conventions). +* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master + +They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. + + + +FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: + + + +{`store.Conventions.FailoverBehavior = FailoverBehavior.ReadFromAllServers + | FailoverBehavior.AllowReadsFromSecondariesAndWritesToSecondaries; +`} + + + + + + + +## **Cluster failover behavior** + +Inside the cluster by default replication bundles in all the servers are enabled. This includes: + +* All instances will be replicated to every server inside the cluster. +* Default failover behavior is `FailoverBehavior.ReadFromLeaderWriteToLeader`. +* Write calls are always referred to the leader (if a write request is made to a none leader server the client will be redirected) +* In the cluster there will be only one leader. In a case the leader is down, a vote will be made to choose another. + +To change a behavior from the client, one can use: + + +{`session.Store(new ReplicationDocument +\{ + ClientConfiguration = new ReplicationClientConfiguration + \{ + FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader + \} + +\}, "Raven/Replication/Destinations"); +`} + + + +The client can load the cluster toplogy from `/cluster/topology` to learn which servers are in the cluster and can be promoted to leader. + +You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option + + + +{`store.Conventions.FailoverBehavior = FailoverBehavior.FailImmediately; +`} + + + +When `FailImmediately` option is used then client will raise exception when primary server is down. + +The remaining values of `FailoverBehavior` enumeration are: + +* *ReadFromLeaderWriteToLeader* (default) - Allows read from leader and write only to leader +* *ReadFromAllWriteToLeader* - Allows read from any server and write only to leader +* *ReadFromAllWriteToLeaderWithFailovers* - Allows read from leader and write only to leader with failovers. +* *ReadFromLeaderWriteToLeaderWithFailovers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master + + +The behaviors `ReadFromAllWriteToLeaderWithFailovers` and `ReadFromLeaderWriteToLeaderWithFailovers` will make the client use the new leader only when trying to write +to a unreachable server. Work only if we configure the Client failover behaviour in the server side to Let client decide . + +![Setting up let client decide on server](../assets/replication-client-configuration-let-client-decide.png) + + + + + + +## **Discovering destinations** + +Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. + +Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. + + + +## **Failover servers** + + +If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. + + +### Setup + + + +{`store.FailoverServers = new FailoverServers(); +store.FailoverServers.ForDefaultDatabase = new[] +\{ + new ReplicationDestination + \{ + Url = "http://localhost:8078", + ApiKey = "apikey" + \}, + new ReplicationDestination + \{ + Url = "http://localhost:8077/", + Database = "test", + Username = "user", + Password = "secret" + \} +\}; + +store.FailoverServers.ForDatabases = new Dictionary +\{ + \{ + "Northwind", + new[] + \{ + new ReplicationDestination + \{ + Url = "http://localhost:8076" + \} + \} + \} +\}; +`} + + + +### Setup using connection string + +To setup a failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use the `Failover` option. Multiple failovers can be setup using multiple `Failover` options. + +Failover +: Type: string in predefined format +: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` +Failover server definition. + +Example: + + + +{`session.Store(new ReplicationDocument +\{ + ClientConfiguration = new ReplicationClientConfiguration + \{ + FailoverBehavior = FailoverBehavior.ReadFromLeaderWriteToLeader + \} + +\}, "Raven/Replication/Destinations"); +`} + + + +Full example: + + + +{` + + +`} + + + + + +## **Setting up default client configuration on server** + +Default client configuration can be 'injected' into a client, by filling out the `ClientConfiguration` property in `Raven/Replication/Destinations`. + +The available options are: + +- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. + +Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. + +![Setting up default client configuration on server](../assets/replication-client-configuration.png) + + + +## **Request redirection** + +The Raven Client API is quite intelligent in this regard, as upon failure it will: + +* Assume that the failure is transient, and retry the request, +* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, +* After ten consecutive failures, Raven will start replicating to this node less often + * Once every 10 requests, until failure count reaches 100 + * Once every 100 requests, until failure count reaches 1,000 + * Once every 1,000 requests, when failure count is above 1,000 +* On the first successful request, the failure count is reset. + +If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. + + + +## **Back to primary** + +The client shifted to a replicated node will go back to its primary server +as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. + + + +## **Replicated operations** + +At a lower level, the following operations support replication: + +* Get - single document and multi documents +* Put +* Delete +* Query +* Rollback +* Commit + +The following operations do not support replication in the Client API: + +* PutIndex +* DeleteIndex + + + +## **Custom document ID generation** + +The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids). +However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect +against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: + + + +{`store + .DatabaseCommands + .Put( +verPrefixForHilo", + null, +Object + \{ +rPrefix", "NorthServer/" \} + \}, +Object()); +`} + + + +The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. +For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. + + + + diff --git a/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx b/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx new file mode 100644 index 0000000000..3503161bd2 --- /dev/null +++ b/versioned_docs/version-3.5/client-api/bundles/content/_how-client-integrates-with-replication-bundle-java.mdx @@ -0,0 +1,207 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +RavenDB's Client API is aware of the replication mechanism offered by the server instances and is ready to support failover scenarios. + +## **Failover behavior** + + By default the client will detect and respond appropriately whenever a server has the replication bundle enabled. This includes: + +* Detecting that an instance is replicating to another set of instances. +* When that instance is down, the client will be automatically shifted to other instances. + +This is caused by a failover mechanism which is turned in a document stored by default. The clinet can load a replication document from `/replication/topology` to learn what replication instances to use if the failover occurred. + + +The client by default creates requests for the replication document even if the server does not have the replication bundle enabled. In this case, the request for `/replication/topology` results in `404` in server logs. + + +You can turn off the failover behavior by using the document store conventions. In order to do so, use `FailImmediately` option: + + + +{`store.getConventions().setFailoverBehavior(FailoverBehaviorSet.of(FailoverBehavior.FAIL_IMMEDIATELY)); +`} + + + +When `FailImmediately` option is used then client will raise exception when primary server is down. + +The remaining values of `FailoverBehavior` enumeration are: + +* *AllowReadsFromSecondaries* (default) - allow to read from secondary server(s), but immediately fail writes to the secondary server(s) +* *AllowReadsFromSecondariesAndWritesToSecondaries* - allow reads from and writes to secondary server(s) +* *ReadFromAllServers* - spread read requests across all servers, instead of doing all the work against master. Write requests will always go to master + +They determine the strategy of the failovers if the primary server is down and the environment is configured to replicate between sibling instances. + + + +FailoverBehavior enumeration values are actually flags and can be combined, e.g. to spread all reads across all servers and allow writes to secondaries one can do as follows: + + + +{`store.getConventions().setFailoverBehavior( + FailoverBehaviorSet.of( + FailoverBehavior.READ_FROM_ALL_SERVERS, + FailoverBehavior.ALLOW_READS_FROM_SECONDARIES_AND_WRITES_TO_SECONDARIES)); +`} + + + + + + + +## **Discovering destinations** + +Once the document store is configured to support failovers, the replication configuration of the database is checked. A list of replicated nodes is then retrieved and saved in the local application storage. Even if it is impossible to reach the primary server in the future, the list will still exist locally, and the document store can try to work with secondary instances, according to the conventions. + +Changes in the server's replication configuration are monitored by the Client API as well. It is done regularly, every 5 minutes, to check if the documents are directed to current instances that are slaves to the primary server, in case a failover occurs. + + + +## **Failover servers** + +If the client cannot reach the primary server and does not have a list of servers, nor is such list available in the local cache, the client will attempt to load and use manually configured failover servers. List of those servers can be configured with `FailoverServers` property in `DocumentStore` or .NET named connection strings. + +### Setup + + + +{`store.setFailoverServers(new FailoverServers()); +ReplicationDestination destination1 = new ReplicationDestination(); +destination1.setUrl("http://localhost:8078"); +destination1.setApiKey("apikey"); + +ReplicationDestination destination2 = new ReplicationDestination(); +destination2.setUrl("http://localhost:8077"); +destination2.setDatabase("test"); +destination2.setUsername("user"); +destination2.setPassword("secret"); +store.getFailoverServers().addForDefaultDatabase(destination1, destination2); + +ReplicationDestination northwindDestination = new ReplicationDestination(); +northwindDestination.setUrl("http://localhost:8076"); + +store.getFailoverServers().addForDatabase("Northwind", northwindDestination); +`} + + + +### Setup using connection string + +To setup failover using a [connection string](../../client-api/setting-up-connection-string.mdx) use `Failover` option. Multiple failovers can be setup using multiple `Failover` options. + +Failover +: Type: string in predefined format +: Format: JSON that can be deserialized to [ReplicationDestination](../../glossary/replication-destination.mdx) with optional database name separated with JSON using pipe ('|') e.g. `Northwind|{ ... }` +Failover server definition. + +Example: + + + +{`Url = http://localhost:59233; + // Primary server url +Failover = \{ Url:'http://localhost:8078'\}; + // Failover for DefaultDatabase +Failover = \{ Url:'http://localhost:8077/', Database:'test'\}; + // Failover for DefaultDatabase with non-default database +Failover = Northwind|\{ Url:'http://localhost:8076/'\}; + // Failover for 'Northwind' database +Failover= \{ Url:'http://localhost:8075', Username:'user', Password:'secret'\}; + // Failover for DefaultDatabase with Username and Password +Failover= \{ Url:'http://localhost:8074', ApiKey:'d5723e19-92ad-4531-adad-8611e6e05c8a'\} + // Failover for DefaultDatabase with ApiKey +`} + + + + + +## **Setting up default client configuration on server** + +Default client configuration can be 'injected' into client, by filling out `ClientConfiguration` property in `Raven/Replication/Destinations`. + +The available options are: + +- `FailoverBehavior` - default failover behavior for all clients that are connecting to a database. + +Default configuration can be altered by The Studio as well. Appropriate settings are available in `Settings -> Replication`. + +![Setting up default client configuration on server](../assets/replication-client-configuration.png) + + + +## **Request redirection** + +The Raven Client API is quite intelligent in this regard, as upon failure it will: + +* Assume that the failure is transient, and retry the request, +* If the second attempt fails as well, will record the failure and shift to a replicated node, if available, +* After ten consecutive failures, Raven will start replicating to this node less often + * Once every 10 requests, until failure count reaches 100 + * Once every 100 requests, until failure count reaches 1,000 + * Once every 1,000 requests, when failure count is above 1,000 +* On the first successful request, the failure count is reset. + +If the second replicated node fails, the same logic applies to it as well, and we move to the third replicated node, and so on. If all nodes fail, an appropriate exception is thrown. + + + +## **Back to primary** + +The client shifted to a replicated node will go back to its primary server +as soon as it becomes reachable (irrespective of the failure count). In replication environment the nodes send heartbeat messages in order to notify destination instances that they are up again. Then the destination (which is the secondary server for our shifted client) will send a feedback message to the client and then try sending a request to the primary server again. If the operation is successful, the failure count will be reset and the communication will work normally. + + + +## **Replicated operations** + +At a lower level, the following operations support replication: + +* Get - single document and multi documents +* Put +* Delete +* Query +* Rollback +* Commit + +The following operations do not support replication in the Client API: + +* PutIndex +* DeleteIndex + + + +## **Custom document ID generation** + +The usage of replication doesn't influence the algorithm of [a document ID generation](../../client-api/document-identifiers/working-with-document-ids.mdx#autogenerated-ids) +However in a Master/Master replication scenario it might be useful to add a server specific prefix to generated document identifiers. This would help to protect +against conflicts of document IDs between the replicating servers. In order to set up the server's prefix you have to put `Raven/ServerPrefixForHilo`: + + + +{`store + .DatabaseCommands + .Put( +verPrefixForHilo", + null, +Object + \{ +rPrefix", "NorthServer/" \} + \}, +Object()); +`} + + + +The *ServerPrefix* value will be fetch in the same request as the current *HiLo* and will also become of a part of generated document IDs. +For example storing a first `User` object will cause that its ID will be `Users/NorthServer/1`. + + + + diff --git a/versioned_docs/version-3.5/client-api/bundles/how-client-integrates-with-replication-bundle.mdx b/versioned_docs/version-3.5/client-api/bundles/how-client-integrates-with-replication-bundle.mdx index fc5f2a1099..38976c8939 100644 --- a/versioned_docs/version-3.5/client-api/bundles/how-client-integrates-with-replication-bundle.mdx +++ b/versioned_docs/version-3.5/client-api/bundles/how-client-integrates-with-replication-bundle.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationBundleCsharp from './_how-client-integrates-with-replication-bundle-csharp.mdx'; -import HowClientIntegratesWithReplicationBundleJava from './_how-client-integrates-with-replication-bundle-java.mdx'; +import HowClientIntegratesWithReplicationBundleCsharp from './content/_how-client-integrates-with-replication-bundle-csharp.mdx'; +import HowClientIntegratesWithReplicationBundleJava from './content/_how-client-integrates-with-replication-bundle-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-data-subscription-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-data-subscription-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-data-subscription-changes-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-data-subscription-changes-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-data-subscription-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-replication-conflicts-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-replication-conflicts-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-replication-conflicts-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-replication-conflicts-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-replication-conflicts-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-transformer-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-transformer-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-transformer-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-transformer-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-transformer-changes-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-transformer-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_how-to-subscribe-to-transformer-changes-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_how-to-subscribe-to-transformer-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-3.5/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-3.5/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-3.5/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx index 5f30dac431..a9e1a1739f 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-bulk-insert-operation-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToBulkInsertOperationChangesCsharp from './_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx'; -import HowToSubscribeToBulkInsertOperationChangesJava from './_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx'; +import HowToSubscribeToBulkInsertOperationChangesCsharp from './content/_how-to-subscribe-to-bulk-insert-operation-changes-csharp.mdx'; +import HowToSubscribeToBulkInsertOperationChangesJava from './content/_how-to-subscribe-to-bulk-insert-operation-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx index 11b8626913..6a9ad5e005 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-data-subscription-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDataSubscriptionChangesCsharp from './_how-to-subscribe-to-data-subscription-changes-csharp.mdx'; -import HowToSubscribeToDataSubscriptionChangesJava from './_how-to-subscribe-to-data-subscription-changes-java.mdx'; +import HowToSubscribeToDataSubscriptionChangesCsharp from './content/_how-to-subscribe-to-data-subscription-changes-csharp.mdx'; +import HowToSubscribeToDataSubscriptionChangesJava from './content/_how-to-subscribe-to-data-subscription-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-document-changes.mdx index 84fcfd9ba3..2328b288d4 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-index-changes.mdx index fe745027fa..35c0d1ac48 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx index c3fc5f89b3..37fc5297ae 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-replication-conflicts.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToReplicationConflictsCsharp from './_how-to-subscribe-to-replication-conflicts-csharp.mdx'; -import HowToSubscribeToReplicationConflictsJava from './_how-to-subscribe-to-replication-conflicts-java.mdx'; +import HowToSubscribeToReplicationConflictsCsharp from './content/_how-to-subscribe-to-replication-conflicts-csharp.mdx'; +import HowToSubscribeToReplicationConflictsJava from './content/_how-to-subscribe-to-replication-conflicts-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-transformer-changes.mdx b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-transformer-changes.mdx index f69a415b0c..a0fefb0ece 100644 --- a/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-transformer-changes.mdx +++ b/versioned_docs/version-3.5/client-api/changes/how-to-subscribe-to-transformer-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTransformerChangesCsharp from './_how-to-subscribe-to-transformer-changes-csharp.mdx'; -import HowToSubscribeToTransformerChangesJava from './_how-to-subscribe-to-transformer-changes-java.mdx'; +import HowToSubscribeToTransformerChangesCsharp from './content/_how-to-subscribe-to-transformer-changes-csharp.mdx'; +import HowToSubscribeToTransformerChangesJava from './content/_how-to-subscribe-to-transformer-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-3.5/client-api/changes/what-is-changes-api.mdx index f1d76c7ebe..8b17716eca 100644 --- a/versioned_docs/version-3.5/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-3.5/client-api/changes/what-is-changes-api.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_delete-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_delete-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_delete-http.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_delete-http.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_delete-java.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_delete-java.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_delete-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_get-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_get-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_get-http.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_get-http.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_get-java.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_get-java.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_get-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_put-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_put-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_put-http.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_put-http.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_put-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/_put-java.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/_put-java.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/content/_put-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/delete.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/delete.mdx index 255c00d87f..0eafa31139 100644 --- a/versioned_docs/version-3.5/client-api/commands/attachments/delete.mdx +++ b/versioned_docs/version-3.5/client-api/commands/attachments/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/get.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/get.mdx index 003c60c1b0..f203a36f83 100644 --- a/versioned_docs/version-3.5/client-api/commands/attachments/get.mdx +++ b/versioned_docs/version-3.5/client-api/commands/attachments/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-http.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-http.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-java.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_get-attachment-metadata-only-java.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_get-attachment-metadata-only-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-http.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-http.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-java.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/attachments/how-to/_update-attachment-metadata-only-java.mdx rename to versioned_docs/version-3.5/client-api/commands/attachments/how-to/content/_update-attachment-metadata-only-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx index fb86765737..0838e34e22 100644 --- a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx +++ b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/get-attachment-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentMetadataOnlyCsharp from './_get-attachment-metadata-only-csharp.mdx'; -import GetAttachmentMetadataOnlyJava from './_get-attachment-metadata-only-java.mdx'; -import GetAttachmentMetadataOnlyHttp from './_get-attachment-metadata-only-http.mdx'; +import GetAttachmentMetadataOnlyCsharp from './content/_get-attachment-metadata-only-csharp.mdx'; +import GetAttachmentMetadataOnlyJava from './content/_get-attachment-metadata-only-java.mdx'; +import GetAttachmentMetadataOnlyHttp from './content/_get-attachment-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx index 463063f241..d9ad940bc8 100644 --- a/versioned_docs/version-3.5/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx +++ b/versioned_docs/version-3.5/client-api/commands/attachments/how-to/update-attachment-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateAttachmentMetadataOnlyCsharp from './_update-attachment-metadata-only-csharp.mdx'; -import UpdateAttachmentMetadataOnlyJava from './_update-attachment-metadata-only-java.mdx'; -import UpdateAttachmentMetadataOnlyHttp from './_update-attachment-metadata-only-http.mdx'; +import UpdateAttachmentMetadataOnlyCsharp from './content/_update-attachment-metadata-only-csharp.mdx'; +import UpdateAttachmentMetadataOnlyJava from './content/_update-attachment-metadata-only-java.mdx'; +import UpdateAttachmentMetadataOnlyHttp from './content/_update-attachment-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/attachments/put.mdx b/versioned_docs/version-3.5/client-api/commands/attachments/put.mdx index 5d5e964e73..1ee613c8b5 100644 --- a/versioned_docs/version-3.5/client-api/commands/attachments/put.mdx +++ b/versioned_docs/version-3.5/client-api/commands/attachments/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-http.mdx b/versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-http.mdx rename to versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-3.5/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-3.5/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 649fbdc2b1..d61bf602a6 100644 --- a/versioned_docs/version-3.5/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-3.5/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchHttp from './_how-to-send-multiple-commands-using-a-batch-http.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchHttp from './content/_how-to-send-multiple-commands-using-a-batch-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/_what-are-commands-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/_what-are-commands-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/_what-are-commands-http.mdx b/versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/_what-are-commands-http.mdx rename to versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/_what-are-commands-java.mdx b/versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/_what-are-commands-java.mdx rename to versioned_docs/version-3.5/client-api/commands/content/_what-are-commands-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_delete-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_delete-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_delete-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_get-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_get-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_put-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_put-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_put-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_stream-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_stream-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_stream-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_stream-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_stream-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_stream-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_stream-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_stream-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/_stream-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/content/_stream-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/_stream-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/content/_stream-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/delete.mdx b/versioned_docs/version-3.5/client-api/commands/documents/delete.mdx index f8ed6a316e..48a372e500 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/documents/get.mdx b/versioned_docs/version-3.5/client-api/commands/documents/get.mdx index 746765561b..a9f16c255b 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_delete-or-update-documents-using-index-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_delete-or-update-documents-using-index-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-http.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-http.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-3.5/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx index da1d526be9..77165fe1f6 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/how-to/delete-or-update-documents-using-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteOrUpdateDocumentsUsingIndexCsharp from './_delete-or-update-documents-using-index-csharp.mdx'; -import DeleteOrUpdateDocumentsUsingIndexJava from './_delete-or-update-documents-using-index-java.mdx'; -import DeleteOrUpdateDocumentsUsingIndexHttp from './_delete-or-update-documents-using-index-http.mdx'; +import DeleteOrUpdateDocumentsUsingIndexCsharp from './content/_delete-or-update-documents-using-index-csharp.mdx'; +import DeleteOrUpdateDocumentsUsingIndexJava from './content/_delete-or-update-documents-using-index-java.mdx'; +import DeleteOrUpdateDocumentsUsingIndexHttp from './content/_delete-or-update-documents-using-index-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-3.5/client-api/commands/documents/how-to/get-document-metadata-only.mdx index b96a821d1f..84c29e6a54 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; -import GetDocumentMetadataOnlyHttp from './_get-document-metadata-only-http.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyHttp from './content/_get-document-metadata-only-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/documents/put.mdx b/versioned_docs/version-3.5/client-api/commands/documents/put.mdx index d9abd08bfd..a295f0a5f8 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/documents/stream.mdx b/versioned_docs/version-3.5/client-api/commands/documents/stream.mdx index 8c0083dbef..3571040d36 100644 --- a/versioned_docs/version-3.5/client-api/commands/documents/stream.mdx +++ b/versioned_docs/version-3.5/client-api/commands/documents/stream.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamCsharp from './_stream-csharp.mdx'; -import StreamJava from './_stream-java.mdx'; -import StreamHttp from './_stream-http.mdx'; +import StreamCsharp from './content/_stream-csharp.mdx'; +import StreamJava from './content/_stream-java.mdx'; +import StreamHttp from './content/_stream-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/compact-database.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/compact-database.mdx index aa76721e79..3f7f8d2890 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/compact-database.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/compact-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseJava from './_compact-database-java.mdx'; -import CompactDatabaseHttp from './_compact-database-http.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseJava from './content/_compact-database-java.mdx'; +import CompactDatabaseHttp from './content/_compact-database-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_compact-database-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_compact-database-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_create-delete-database-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_create-delete-database-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_disable-caching-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_disable-caching-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_disable-caching-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_disable-caching-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_disable-caching-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_disable-caching-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-and-server-statistics-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-and-server-statistics-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-database-configuration-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-database-configuration-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-full-url-for-a-document-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-full-url-for-a-document-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-full-url-for-a-document-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-full-url-for-a-document-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-full-url-for-a-document-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-full-url-for-a-document-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-full-url-for-a-document-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-full-url-for-a-document-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-names-of-all-databases-on-a-server-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-names-of-all-databases-on-a-server-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_get-server-build-number-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_get-server-build-number-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-backup-restore-operations-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-backup-restore-operations-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-indexing-and-get-indexing-status-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-indexing-and-get-indexing-status-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-reducing-http.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-reducing-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_start-stop-reducing-http.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_start-stop-reducing-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-credentials-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-credentials-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-credentials-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-credentials-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-credentials-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-credentials-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-credentials-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-credentials-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-to-a-different-database-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-to-a-different-database-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-to-a-different-database-java.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/how-to/_switch-commands-to-a-different-database-java.mdx rename to versioned_docs/version-3.5/client-api/commands/how-to/content/_switch-commands-to-a-different-database-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/create-delete-database.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/create-delete-database.mdx index d8df725f6d..c2fd7786aa 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/create-delete-database.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/create-delete-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDeleteDatabaseCsharp from './_create-delete-database-csharp.mdx'; -import CreateDeleteDatabaseJava from './_create-delete-database-java.mdx'; -import CreateDeleteDatabaseHttp from './_create-delete-database-http.mdx'; +import CreateDeleteDatabaseCsharp from './content/_create-delete-database-csharp.mdx'; +import CreateDeleteDatabaseJava from './content/_create-delete-database-java.mdx'; +import CreateDeleteDatabaseHttp from './content/_create-delete-database-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/disable-caching.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/disable-caching.mdx index 3e8d448875..2751aa36e0 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/disable-caching.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableCachingCsharp from './_disable-caching-csharp.mdx'; -import DisableCachingJava from './_disable-caching-java.mdx'; +import DisableCachingCsharp from './content/_disable-caching-csharp.mdx'; +import DisableCachingJava from './content/_disable-caching-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/get-database-and-server-statistics.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/get-database-and-server-statistics.mdx index 337c0c7c9b..455f7eec00 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/get-database-and-server-statistics.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/get-database-and-server-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseAndServerStatisticsCsharp from './_get-database-and-server-statistics-csharp.mdx'; -import GetDatabaseAndServerStatisticsJava from './_get-database-and-server-statistics-java.mdx'; -import GetDatabaseAndServerStatisticsHttp from './_get-database-and-server-statistics-http.mdx'; +import GetDatabaseAndServerStatisticsCsharp from './content/_get-database-and-server-statistics-csharp.mdx'; +import GetDatabaseAndServerStatisticsJava from './content/_get-database-and-server-statistics-java.mdx'; +import GetDatabaseAndServerStatisticsHttp from './content/_get-database-and-server-statistics-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/get-database-configuration.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/get-database-configuration.mdx index 8bdcbb6d78..28ef7c3272 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/get-database-configuration.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/get-database-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseConfigurationCsharp from './_get-database-configuration-csharp.mdx'; -import GetDatabaseConfigurationJava from './_get-database-configuration-java.mdx'; -import GetDatabaseConfigurationHttp from './_get-database-configuration-http.mdx'; +import GetDatabaseConfigurationCsharp from './content/_get-database-configuration-csharp.mdx'; +import GetDatabaseConfigurationJava from './content/_get-database-configuration-java.mdx'; +import GetDatabaseConfigurationHttp from './content/_get-database-configuration-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/get-full-url-for-a-document.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/get-full-url-for-a-document.mdx index 46e7f159ff..c6b06afa22 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/get-full-url-for-a-document.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/get-full-url-for-a-document.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetFullUrlForADocumentCsharp from './_get-full-url-for-a-document-csharp.mdx'; -import GetFullUrlForADocumentJava from './_get-full-url-for-a-document-java.mdx'; +import GetFullUrlForADocumentCsharp from './content/_get-full-url-for-a-document-csharp.mdx'; +import GetFullUrlForADocumentJava from './content/_get-full-url-for-a-document-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx index 8ead334768..9c4558a8e2 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/get-names-of-all-databases-on-a-server.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesOfAllDatabasesOnAServerCsharp from './_get-names-of-all-databases-on-a-server-csharp.mdx'; -import GetNamesOfAllDatabasesOnAServerJava from './_get-names-of-all-databases-on-a-server-java.mdx'; -import GetNamesOfAllDatabasesOnAServerHttp from './_get-names-of-all-databases-on-a-server-http.mdx'; +import GetNamesOfAllDatabasesOnAServerCsharp from './content/_get-names-of-all-databases-on-a-server-csharp.mdx'; +import GetNamesOfAllDatabasesOnAServerJava from './content/_get-names-of-all-databases-on-a-server-java.mdx'; +import GetNamesOfAllDatabasesOnAServerHttp from './content/_get-names-of-all-databases-on-a-server-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/get-server-build-number.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/get-server-build-number.mdx index 93387cf0fb..95d56e9833 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/get-server-build-number.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/get-server-build-number.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerBuildNumberCsharp from './_get-server-build-number-csharp.mdx'; -import GetServerBuildNumberJava from './_get-server-build-number-java.mdx'; -import GetServerBuildNumberHttp from './_get-server-build-number-http.mdx'; +import GetServerBuildNumberCsharp from './content/_get-server-build-number-csharp.mdx'; +import GetServerBuildNumberJava from './content/_get-server-build-number-java.mdx'; +import GetServerBuildNumberHttp from './content/_get-server-build-number-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/start-backup-restore-operations.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/start-backup-restore-operations.mdx index 196ec5549b..cdc2df66c4 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/start-backup-restore-operations.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/start-backup-restore-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartBackupRestoreOperationsCsharp from './_start-backup-restore-operations-csharp.mdx'; -import StartBackupRestoreOperationsJava from './_start-backup-restore-operations-java.mdx'; -import StartBackupRestoreOperationsHttp from './_start-backup-restore-operations-http.mdx'; +import StartBackupRestoreOperationsCsharp from './content/_start-backup-restore-operations-csharp.mdx'; +import StartBackupRestoreOperationsJava from './content/_start-backup-restore-operations-java.mdx'; +import StartBackupRestoreOperationsHttp from './content/_start-backup-restore-operations-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx index 77c163a21a..357c1f407d 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-indexing-and-get-indexing-status.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartStopIndexingAndGetIndexingStatusCsharp from './_start-stop-indexing-and-get-indexing-status-csharp.mdx'; -import StartStopIndexingAndGetIndexingStatusJava from './_start-stop-indexing-and-get-indexing-status-java.mdx'; -import StartStopIndexingAndGetIndexingStatusHttp from './_start-stop-indexing-and-get-indexing-status-http.mdx'; +import StartStopIndexingAndGetIndexingStatusCsharp from './content/_start-stop-indexing-and-get-indexing-status-csharp.mdx'; +import StartStopIndexingAndGetIndexingStatusJava from './content/_start-stop-indexing-and-get-indexing-status-java.mdx'; +import StartStopIndexingAndGetIndexingStatusHttp from './content/_start-stop-indexing-and-get-indexing-status-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-reducing.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-reducing.mdx index a7d08e83aa..6083caed34 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-reducing.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/start-stop-reducing.mdx @@ -8,7 +8,7 @@ supported_languages: ["http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartStopReducingHttp from './_start-stop-reducing-http.mdx'; +import StartStopReducingHttp from './content/_start-stop-reducing-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-credentials.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-credentials.mdx index 5efcd15ad4..c761aba857 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-credentials.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-credentials.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchCommandsCredentialsCsharp from './_switch-commands-credentials-csharp.mdx'; -import SwitchCommandsCredentialsJava from './_switch-commands-credentials-java.mdx'; +import SwitchCommandsCredentialsCsharp from './content/_switch-commands-credentials-csharp.mdx'; +import SwitchCommandsCredentialsJava from './content/_switch-commands-credentials-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-to-a-different-database.mdx b/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-to-a-different-database.mdx index 2faeac42a8..57e43ce4a7 100644 --- a/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-to-a-different-database.mdx +++ b/versioned_docs/version-3.5/client-api/commands/how-to/switch-commands-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchCommandsToADifferentDatabaseCsharp from './_switch-commands-to-a-different-database-csharp.mdx'; -import SwitchCommandsToADifferentDatabaseJava from './_switch-commands-to-a-different-database-java.mdx'; +import SwitchCommandsToADifferentDatabaseCsharp from './content/_switch-commands-to-a-different-database-csharp.mdx'; +import SwitchCommandsToADifferentDatabaseJava from './content/_switch-commands-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_delete-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_delete-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_delete-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_delete-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_delete-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_delete-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_delete-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_get-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_get-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_get-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_get-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_get-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_get-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_get-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_put-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_put-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_put-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_put-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_put-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/_put-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/_put-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/content/_put-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/delete.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/delete.mdx index 3b1eeceffc..bc959e7274 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/delete.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/get.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/get.mdx index 78fd5e2262..de0293dee5 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/get.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-lock-mode.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-lock-mode.mdx index cea5b64ae7..3dbceb3e7a 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-lock-mode.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-lock-mode.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeIndexLockModeCsharp from './_change-index-lock-mode-csharp.mdx'; -import ChangeIndexLockModeJava from './_change-index-lock-mode-java.mdx'; +import ChangeIndexLockModeCsharp from './content/_change-index-lock-mode-csharp.mdx'; +import ChangeIndexLockModeJava from './content/_change-index-lock-mode-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-priority.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-priority.mdx index fcf8018071..366df76f67 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-priority.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/change-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeIndexPriorityCsharp from './_change-index-priority-csharp.mdx'; -import ChangeIndexPriorityJava from './_change-index-priority-java.mdx'; +import ChangeIndexPriorityCsharp from './content/_change-index-priority-csharp.mdx'; +import ChangeIndexPriorityJava from './content/_change-index-priority-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx index 53d3ec3417..3f9595b48c 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/check-if-index-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfIndexHasChangedCsharp from './_check-if-index-has-changed-csharp.mdx'; -import CheckIfIndexHasChangedJava from './_check-if-index-has-changed-java.mdx'; -import CheckIfIndexHasChangedHttp from './_check-if-index-has-changed-http.mdx'; +import CheckIfIndexHasChangedCsharp from './content/_check-if-index-has-changed-csharp.mdx'; +import CheckIfIndexHasChangedJava from './content/_check-if-index-has-changed-java.mdx'; +import CheckIfIndexHasChangedHttp from './content/_check-if-index-has-changed-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-lock-mode-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-lock-mode-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-lock-mode-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-lock-mode-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-lock-mode-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-lock-mode-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-lock-mode-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-lock-mode-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-priority-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-priority-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-priority-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-priority-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_change-index-priority-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_change-index-priority-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_check-if-index-has-changed-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_check-if-index-has-changed-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-merge-suggestions-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-merge-suggestions-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_get-index-terms-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_get-index-terms-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-http.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-http.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-java.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/indexes/how-to/_reset-index-java.mdx rename to versioned_docs/version-3.5/client-api/commands/indexes/how-to/content/_reset-index-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx index 289c6799bf..23ae6a0068 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-merge-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexMergeSuggestionsCsharp from './_get-index-merge-suggestions-csharp.mdx'; -import GetIndexMergeSuggestionsJava from './_get-index-merge-suggestions-java.mdx'; -import GetIndexMergeSuggestionsHttp from './_get-index-merge-suggestions-http.mdx'; +import GetIndexMergeSuggestionsCsharp from './content/_get-index-merge-suggestions-csharp.mdx'; +import GetIndexMergeSuggestionsJava from './content/_get-index-merge-suggestions-java.mdx'; +import GetIndexMergeSuggestionsHttp from './content/_get-index-merge-suggestions-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-terms.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-terms.mdx index df8b0bcbaf..2d2d3b1fcc 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-terms.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/get-index-terms.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexTermsCsharp from './_get-index-terms-csharp.mdx'; -import GetIndexTermsJava from './_get-index-terms-java.mdx'; -import GetIndexTermsHttp from './_get-index-terms-http.mdx'; +import GetIndexTermsCsharp from './content/_get-index-terms-csharp.mdx'; +import GetIndexTermsJava from './content/_get-index-terms-java.mdx'; +import GetIndexTermsHttp from './content/_get-index-terms-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/reset-index.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/reset-index.mdx index 1a99792f5e..7897d1deee 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/how-to/reset-index.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/how-to/reset-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexHttp from './_reset-index-http.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexHttp from './content/_reset-index-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/indexes/put.mdx b/versioned_docs/version-3.5/client-api/commands/indexes/put.mdx index b00b3371b6..f3795ee945 100644 --- a/versioned_docs/version-3.5/client-api/commands/indexes/put.mdx +++ b/versioned_docs/version-3.5/client-api/commands/indexes/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-http.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-http.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-java.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-use-javascript-to-patch-your-documents-java.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-use-javascript-to-patch-your-documents-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-http.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-http.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-java.mdx b/versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/patches/_how-to-work-with-patch-requests-java.mdx rename to versioned_docs/version-3.5/client-api/commands/patches/content/_how-to-work-with-patch-requests-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx b/versioned_docs/version-3.5/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx index 87f42ae8f6..f9611a6591 100644 --- a/versioned_docs/version-3.5/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx +++ b/versioned_docs/version-3.5/client-api/commands/patches/how-to-use-javascript-to-patch-your-documents.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseJavascriptToPatchYourDocumentsCsharp from './_how-to-use-javascript-to-patch-your-documents-csharp.mdx'; -import HowToUseJavascriptToPatchYourDocumentsJava from './_how-to-use-javascript-to-patch-your-documents-java.mdx'; -import HowToUseJavascriptToPatchYourDocumentsHttp from './_how-to-use-javascript-to-patch-your-documents-http.mdx'; +import HowToUseJavascriptToPatchYourDocumentsCsharp from './content/_how-to-use-javascript-to-patch-your-documents-csharp.mdx'; +import HowToUseJavascriptToPatchYourDocumentsJava from './content/_how-to-use-javascript-to-patch-your-documents-java.mdx'; +import HowToUseJavascriptToPatchYourDocumentsHttp from './content/_how-to-use-javascript-to-patch-your-documents-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/patches/how-to-work-with-patch-requests.mdx b/versioned_docs/version-3.5/client-api/commands/patches/how-to-work-with-patch-requests.mdx index 68f473a7f2..86bc26b036 100644 --- a/versioned_docs/version-3.5/client-api/commands/patches/how-to-work-with-patch-requests.mdx +++ b/versioned_docs/version-3.5/client-api/commands/patches/how-to-work-with-patch-requests.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithPatchRequestsCsharp from './_how-to-work-with-patch-requests-csharp.mdx'; -import HowToWorkWithPatchRequestsJava from './_how-to-work-with-patch-requests-java.mdx'; -import HowToWorkWithPatchRequestsHttp from './_how-to-work-with-patch-requests-http.mdx'; +import HowToWorkWithPatchRequestsCsharp from './content/_how-to-work-with-patch-requests-csharp.mdx'; +import HowToWorkWithPatchRequestsJava from './content/_how-to-work-with-patch-requests-java.mdx'; +import HowToWorkWithPatchRequestsHttp from './content/_how-to-work-with-patch-requests-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-http.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-http.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-java.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-query-a-database-java.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-query-a-database-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-http.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-http.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-http.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-http.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-java.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-facet-query-java.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-facet-query-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-http.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-http.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-java.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-morelikethis-query-java.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-morelikethis-query-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-http.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-http.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-java.mdx b/versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/querying/_how-to-work-with-suggestion-query-java.mdx rename to versioned_docs/version-3.5/client-api/commands/querying/content/_how-to-work-with-suggestion-query-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/querying/how-to-query-a-database.mdx b/versioned_docs/version-3.5/client-api/commands/querying/how-to-query-a-database.mdx index a4176931b1..9b2f03c01d 100644 --- a/versioned_docs/version-3.5/client-api/commands/querying/how-to-query-a-database.mdx +++ b/versioned_docs/version-3.5/client-api/commands/querying/how-to-query-a-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryADatabaseCsharp from './_how-to-query-a-database-csharp.mdx'; -import HowToQueryADatabaseJava from './_how-to-query-a-database-java.mdx'; -import HowToQueryADatabaseHttp from './_how-to-query-a-database-http.mdx'; +import HowToQueryADatabaseCsharp from './content/_how-to-query-a-database-csharp.mdx'; +import HowToQueryADatabaseJava from './content/_how-to-query-a-database-java.mdx'; +import HowToQueryADatabaseHttp from './content/_how-to-query-a-database-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/querying/how-to-stream-query-results.mdx b/versioned_docs/version-3.5/client-api/commands/querying/how-to-stream-query-results.mdx index d5880a64ec..2c444a3955 100644 --- a/versioned_docs/version-3.5/client-api/commands/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-3.5/client-api/commands/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsHttp from './_how-to-stream-query-results-http.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsHttp from './content/_how-to-stream-query-results-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-facet-query.mdx b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-facet-query.mdx index e46a82616f..1ae5ef8efe 100644 --- a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-facet-query.mdx +++ b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-facet-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithFacetQueryCsharp from './_how-to-work-with-facet-query-csharp.mdx'; -import HowToWorkWithFacetQueryJava from './_how-to-work-with-facet-query-java.mdx'; -import HowToWorkWithFacetQueryHttp from './_how-to-work-with-facet-query-http.mdx'; +import HowToWorkWithFacetQueryCsharp from './content/_how-to-work-with-facet-query-csharp.mdx'; +import HowToWorkWithFacetQueryJava from './content/_how-to-work-with-facet-query-java.mdx'; +import HowToWorkWithFacetQueryHttp from './content/_how-to-work-with-facet-query-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx index 3086bb0a29..71c7e0a2b8 100644 --- a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx +++ b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-morelikethis-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithMorelikethisQueryCsharp from './_how-to-work-with-morelikethis-query-csharp.mdx'; -import HowToWorkWithMorelikethisQueryJava from './_how-to-work-with-morelikethis-query-java.mdx'; -import HowToWorkWithMorelikethisQueryHttp from './_how-to-work-with-morelikethis-query-http.mdx'; +import HowToWorkWithMorelikethisQueryCsharp from './content/_how-to-work-with-morelikethis-query-csharp.mdx'; +import HowToWorkWithMorelikethisQueryJava from './content/_how-to-work-with-morelikethis-query-java.mdx'; +import HowToWorkWithMorelikethisQueryHttp from './content/_how-to-work-with-morelikethis-query-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-suggestion-query.mdx b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-suggestion-query.mdx index 75d35334ac..2e366b7a84 100644 --- a/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-suggestion-query.mdx +++ b/versioned_docs/version-3.5/client-api/commands/querying/how-to-work-with-suggestion-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionQueryCsharp from './_how-to-work-with-suggestion-query-csharp.mdx'; -import HowToWorkWithSuggestionQueryJava from './_how-to-work-with-suggestion-query-java.mdx'; -import HowToWorkWithSuggestionQueryHttp from './_how-to-work-with-suggestion-query-http.mdx'; +import HowToWorkWithSuggestionQueryCsharp from './content/_how-to-work-with-suggestion-query-csharp.mdx'; +import HowToWorkWithSuggestionQueryJava from './content/_how-to-work-with-suggestion-query-java.mdx'; +import HowToWorkWithSuggestionQueryHttp from './content/_how-to-work-with-suggestion-query-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_delete-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_delete-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_delete-http.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_delete-http.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_delete-java.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_delete-java.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_delete-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_get-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_get-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_get-http.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_get-http.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_get-java.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_get-java.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_get-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_put-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_put-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_put-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_put-http.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_put-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_put-http.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_put-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/_put-java.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/_put-java.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/content/_put-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/delete.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/delete.mdx index bebeffe4df..b4665f4088 100644 --- a/versioned_docs/version-3.5/client-api/commands/transformers/delete.mdx +++ b/versioned_docs/version-3.5/client-api/commands/transformers/delete.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/get.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/get.mdx index d7be4372d9..e7611ae03f 100644 --- a/versioned_docs/version-3.5/client-api/commands/transformers/get.mdx +++ b/versioned_docs/version-3.5/client-api/commands/transformers/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx index 0712d524c0..f7909e6b51 100644 --- a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx +++ b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/change-transformer-lock-mode.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangeTransformerLockModeCsharp from './_change-transformer-lock-mode-csharp.mdx'; -import ChangeTransformerLockModeJava from './_change-transformer-lock-mode-java.mdx'; -import ChangeTransformerLockModeHttp from './_change-transformer-lock-mode-http.mdx'; +import ChangeTransformerLockModeCsharp from './content/_change-transformer-lock-mode-csharp.mdx'; +import ChangeTransformerLockModeJava from './content/_change-transformer-lock-mode-java.mdx'; +import ChangeTransformerLockModeHttp from './content/_change-transformer-lock-mode-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-http.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-http.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-java.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_change-transformer-lock-mode-java.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_change-transformer-lock-mode-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-csharp.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-csharp.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-http.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-http.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-http.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-http.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-java.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/commands/transformers/how-to/_transform-query-results-java.mdx rename to versioned_docs/version-3.5/client-api/commands/transformers/how-to/content/_transform-query-results-java.mdx diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/transform-query-results.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/transform-query-results.mdx index cf34643517..ca07a031b1 100644 --- a/versioned_docs/version-3.5/client-api/commands/transformers/how-to/transform-query-results.mdx +++ b/versioned_docs/version-3.5/client-api/commands/transformers/how-to/transform-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TransformQueryResultsCsharp from './_transform-query-results-csharp.mdx'; -import TransformQueryResultsJava from './_transform-query-results-java.mdx'; -import TransformQueryResultsHttp from './_transform-query-results-http.mdx'; +import TransformQueryResultsCsharp from './content/_transform-query-results-csharp.mdx'; +import TransformQueryResultsJava from './content/_transform-query-results-java.mdx'; +import TransformQueryResultsHttp from './content/_transform-query-results-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/transformers/put.mdx b/versioned_docs/version-3.5/client-api/commands/transformers/put.mdx index c262076493..c87b5c1ced 100644 --- a/versioned_docs/version-3.5/client-api/commands/transformers/put.mdx +++ b/versioned_docs/version-3.5/client-api/commands/transformers/put.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutHttp from './_put-http.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutHttp from './content/_put-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/commands/what-are-commands.mdx b/versioned_docs/version-3.5/client-api/commands/what-are-commands.mdx index a1f7fbf7b1..353d1c9ac9 100644 --- a/versioned_docs/version-3.5/client-api/commands/what-are-commands.mdx +++ b/versioned_docs/version-3.5/client-api/commands/what-are-commands.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreCommandsCsharp from './_what-are-commands-csharp.mdx'; -import WhatAreCommandsJava from './_what-are-commands-java.mdx'; -import WhatAreCommandsHttp from './_what-are-commands-http.mdx'; +import WhatAreCommandsCsharp from './content/_what-are-commands-csharp.mdx'; +import WhatAreCommandsJava from './content/_what-are-commands-java.mdx'; +import WhatAreCommandsHttp from './content/_what-are-commands-http.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/caching.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/caching.mdx index 6d4977909d..4dabb4ef14 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/caching.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CachingCsharp from './_caching-csharp.mdx'; -import CachingJava from './_caching-java.mdx'; +import CachingCsharp from './content/_caching-csharp.mdx'; +import CachingJava from './content/_caching-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_caching-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_caching-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_caching-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_caching-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_caching-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_caching-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_caching-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_misc-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_misc-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_misc-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_misc-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_misc-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_misc-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_misc-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_misc-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_querying-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_querying-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_querying-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_querying-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_querying-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_querying-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_replication-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_replication-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_replication-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_replication-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_replication-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_replication-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_replication-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_replication-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_request-handling-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_request-handling-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_request-handling-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_request-handling-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_request-handling-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_request-handling-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_request-handling-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_request-handling-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_what-are-conventions-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_what-are-conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_what-are-conventions-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_what-are-conventions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/_what-are-conventions-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/content/_what-are-conventions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/_what-are-conventions-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/content/_what-are-conventions-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_global-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_global-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_global-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/global.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/global.mdx index cff4d2d4ac..4b5cb4e368 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/global.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/global.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/type-specific.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/type-specific.mdx index 20b5e53b78..2e28d95b3f 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/identifier-generation/type-specific.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/misc.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/misc.mdx index 406687d77b..5bef509f9b 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/misc.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/misc.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MiscCsharp from './_misc-csharp.mdx'; -import MiscJava from './_misc-java.mdx'; +import MiscCsharp from './content/_misc-csharp.mdx'; +import MiscJava from './content/_misc-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/querying.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/querying.mdx index def33fc71a..733f22d7ef 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/querying.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/replication.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/replication.mdx index 00a6ebc0d0..e77cf0381c 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/replication.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/replication.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReplicationCsharp from './_replication-csharp.mdx'; -import ReplicationJava from './_replication-java.mdx'; +import ReplicationCsharp from './content/_replication-csharp.mdx'; +import ReplicationJava from './content/_replication-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/request-handling.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/request-handling.mdx index 0e8f166796..ade4360cb9 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/request-handling.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/request-handling.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RequestHandlingCsharp from './_request-handling-csharp.mdx'; -import RequestHandlingJava from './_request-handling-java.mdx'; +import RequestHandlingCsharp from './content/_request-handling-csharp.mdx'; +import RequestHandlingJava from './content/_request-handling-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/configuration/conventions/what-are-conventions.mdx b/versioned_docs/version-3.5/client-api/configuration/conventions/what-are-conventions.mdx index a7a4955523..d1f0819d22 100644 --- a/versioned_docs/version-3.5/client-api/configuration/conventions/what-are-conventions.mdx +++ b/versioned_docs/version-3.5/client-api/configuration/conventions/what-are-conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConventionsCsharp from './_what-are-conventions-csharp.mdx'; -import WhatAreConventionsJava from './_what-are-conventions-java.mdx'; +import WhatAreConventionsCsharp from './content/_what-are-conventions-csharp.mdx'; +import WhatAreConventionsJava from './content/_what-are-conventions-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-3.5/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-3.5/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/_creating-document-store-java.mdx b/versioned_docs/version-3.5/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-3.5/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-3.5/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-3.5/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-3.5/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/_setting-up-connection-string-csharp.mdx b/versioned_docs/version-3.5/client-api/content/_setting-up-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_setting-up-connection-string-csharp.mdx rename to versioned_docs/version-3.5/client-api/content/_setting-up-connection-string-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/_setting-up-connection-string-java.mdx b/versioned_docs/version-3.5/client-api/content/_setting-up-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_setting-up-connection-string-java.mdx rename to versioned_docs/version-3.5/client-api/content/_setting-up-connection-string-java.mdx diff --git a/versioned_docs/version-3.5/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-3.5/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-3.5/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-3.5/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-3.5/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-3.5/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-3.5/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-3.5/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-3.5/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-3.5/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-3.5/client-api/creating-document-store.mdx b/versioned_docs/version-3.5/client-api/creating-document-store.mdx index 308b21972e..34dfe3abf0 100644 --- a/versioned_docs/version-3.5/client-api/creating-document-store.mdx +++ b/versioned_docs/version-3.5/client-api/creating-document-store.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_events-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_events-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_events-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_events-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_events-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_events-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_events-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_events-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-delete-data-subscription-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-delete-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-delete-data-subscription-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-delete-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-delete-data-subscription-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-delete-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-delete-data-subscription-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-delete-data-subscription-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-get-subscriptions-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-get-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-get-subscriptions-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-get-subscriptions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-get-subscriptions-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-get-subscriptions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-get-subscriptions-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-get-subscriptions-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-open-data-subscription-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-open-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-open-data-subscription-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-open-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-open-data-subscription-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-open-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-open-data-subscription-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-open-data-subscription-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-release-data-subscription-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-release-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-release-data-subscription-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-release-data-subscription-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-release-data-subscription-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-release-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_how-to-release-data-subscription-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_how-to-release-data-subscription-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx rename to versioned_docs/version-3.5/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/events.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/events.mdx index 7a984b50df..37df376812 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/events.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/events.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EventsCsharp from './_events-csharp.mdx'; -import EventsJava from './_events-java.mdx'; +import EventsCsharp from './content/_events-csharp.mdx'; +import EventsJava from './content/_events-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-create-data-subscription.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-create-data-subscription.mdx index a7a5a98486..ad5b46e9a4 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-create-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-delete-data-subscription.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-delete-data-subscription.mdx index 09769c756c..2e6519556a 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-delete-data-subscription.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-delete-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDeleteDataSubscriptionCsharp from './_how-to-delete-data-subscription-csharp.mdx'; -import HowToDeleteDataSubscriptionJava from './_how-to-delete-data-subscription-java.mdx'; +import HowToDeleteDataSubscriptionCsharp from './content/_how-to-delete-data-subscription-csharp.mdx'; +import HowToDeleteDataSubscriptionJava from './content/_how-to-delete-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-get-subscriptions.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-get-subscriptions.mdx index 88bce1312e..037610a4ac 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-get-subscriptions.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-get-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetSubscriptionsCsharp from './_how-to-get-subscriptions-csharp.mdx'; -import HowToGetSubscriptionsJava from './_how-to-get-subscriptions-java.mdx'; +import HowToGetSubscriptionsCsharp from './content/_how-to-get-subscriptions-csharp.mdx'; +import HowToGetSubscriptionsJava from './content/_how-to-get-subscriptions-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-open-data-subscription.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-open-data-subscription.mdx index da4c1f3961..61b7884c7d 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-open-data-subscription.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-open-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToOpenDataSubscriptionCsharp from './_how-to-open-data-subscription-csharp.mdx'; -import HowToOpenDataSubscriptionJava from './_how-to-open-data-subscription-java.mdx'; +import HowToOpenDataSubscriptionCsharp from './content/_how-to-open-data-subscription-csharp.mdx'; +import HowToOpenDataSubscriptionJava from './content/_how-to-open-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-release-data-subscription.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-release-data-subscription.mdx index 9becdf05d7..c1ea5f9308 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-release-data-subscription.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/how-to-release-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToReleaseDataSubscriptionCsharp from './_how-to-release-data-subscription-csharp.mdx'; -import HowToReleaseDataSubscriptionJava from './_how-to-release-data-subscription-java.mdx'; +import HowToReleaseDataSubscriptionCsharp from './content/_how-to-release-data-subscription-csharp.mdx'; +import HowToReleaseDataSubscriptionJava from './content/_how-to-release-data-subscription-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-3.5/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 2b339597f2..967ee7cf59 100644 --- a/versioned_docs/version-3.5/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-3.5/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/how-to/_enable-profiling-csharp.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_enable-profiling-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_enable-profiling-csharp.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_enable-profiling-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-java.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_send-custom-request-using-httpjsonrequestfactory-java.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_send-custom-request-using-httpjsonrequestfactory-java.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_work-with-authentication-csharp.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_work-with-authentication-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_work-with-authentication-csharp.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_work-with-authentication-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/_work-with-authentication-java.mdx b/versioned_docs/version-3.5/client-api/how-to/content/_work-with-authentication-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/how-to/_work-with-authentication-java.mdx rename to versioned_docs/version-3.5/client-api/how-to/content/_work-with-authentication-java.mdx diff --git a/versioned_docs/version-3.5/client-api/how-to/enable-profiling.mdx b/versioned_docs/version-3.5/client-api/how-to/enable-profiling.mdx index a6c75be981..87ce5c3694 100644 --- a/versioned_docs/version-3.5/client-api/how-to/enable-profiling.mdx +++ b/versioned_docs/version-3.5/client-api/how-to/enable-profiling.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableProfilingCsharp from './_enable-profiling-csharp.mdx'; +import EnableProfilingCsharp from './content/_enable-profiling-csharp.mdx'; diff --git a/versioned_docs/version-3.5/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx b/versioned_docs/version-3.5/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx index bff961b266..66b4eee05c 100644 --- a/versioned_docs/version-3.5/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx +++ b/versioned_docs/version-3.5/client-api/how-to/send-custom-request-using-httpjsonrequestfactory.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SendCustomRequestUsingHttpjsonrequestfactoryCsharp from './_send-custom-request-using-httpjsonrequestfactory-csharp.mdx'; -import SendCustomRequestUsingHttpjsonrequestfactoryJava from './_send-custom-request-using-httpjsonrequestfactory-java.mdx'; +import SendCustomRequestUsingHttpjsonrequestfactoryCsharp from './content/_send-custom-request-using-httpjsonrequestfactory-csharp.mdx'; +import SendCustomRequestUsingHttpjsonrequestfactoryJava from './content/_send-custom-request-using-httpjsonrequestfactory-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-3.5/client-api/how-to/setup-aggressive-caching.mdx index 3020188adb..970f58ef18 100644 --- a/versioned_docs/version-3.5/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-3.5/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/how-to/work-with-authentication.mdx b/versioned_docs/version-3.5/client-api/how-to/work-with-authentication.mdx index 94664db7d5..e9bf7b11f9 100644 --- a/versioned_docs/version-3.5/client-api/how-to/work-with-authentication.mdx +++ b/versioned_docs/version-3.5/client-api/how-to/work-with-authentication.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkWithAuthenticationCsharp from './_work-with-authentication-csharp.mdx'; -import WorkWithAuthenticationJava from './_work-with-authentication-java.mdx'; +import WorkWithAuthenticationCsharp from './content/_work-with-authentication-csharp.mdx'; +import WorkWithAuthenticationJava from './content/_work-with-authentication-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-listeners-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-listeners-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-listeners-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-listeners-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-listeners-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-listeners-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-listeners-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-query-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-java.mdx b/versioned_docs/version-3.5/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/listeners/_what-are-store-listeners-and-how-to-work-with-them-java.mdx rename to versioned_docs/version-3.5/client-api/listeners/content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx index 27817c3a65..3eecbd1c26 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-conflict-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConflictListenersAndHowToWorkWithThemCsharp from './_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreConflictListenersAndHowToWorkWithThemJava from './_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreConflictListenersAndHowToWorkWithThemCsharp from './content/_what-are-conflict-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreConflictListenersAndHowToWorkWithThemJava from './content/_what-are-conflict-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx index 3b73745d1e..1b441401e0 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-conversion-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreConversionListenersAndHowToWorkWithThemCsharp from './_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreConversionListenersAndHowToWorkWithThemJava from './_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreConversionListenersAndHowToWorkWithThemCsharp from './content/_what-are-conversion-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreConversionListenersAndHowToWorkWithThemJava from './content/_what-are-conversion-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx index 0eaf2e0353..363f29f0c1 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-delete-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDeleteListenersAndHowToWorkWithThemCsharp from './_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreDeleteListenersAndHowToWorkWithThemJava from './_what-are-delete-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreDeleteListenersAndHowToWorkWithThemCsharp from './content/_what-are-delete-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreDeleteListenersAndHowToWorkWithThemJava from './content/_what-are-delete-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-listeners.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-listeners.mdx index e69346f0a4..6771419303 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-listeners.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-listeners.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreListenersCsharp from './_what-are-listeners-csharp.mdx'; -import WhatAreListenersJava from './_what-are-listeners-java.mdx'; +import WhatAreListenersCsharp from './content/_what-are-listeners-csharp.mdx'; +import WhatAreListenersJava from './content/_what-are-listeners-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx index 4e58413a84..ede72a5938 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-query-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreQueryListenersAndHowToWorkWithThemCsharp from './_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreQueryListenersAndHowToWorkWithThemJava from './_what-are-query-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreQueryListenersAndHowToWorkWithThemCsharp from './content/_what-are-query-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreQueryListenersAndHowToWorkWithThemJava from './content/_what-are-query-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx b/versioned_docs/version-3.5/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx index 09d609feec..0b02d97661 100644 --- a/versioned_docs/version-3.5/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx +++ b/versioned_docs/version-3.5/client-api/listeners/what-are-store-listeners-and-how-to-work-with-them.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreStoreListenersAndHowToWorkWithThemCsharp from './_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx'; -import WhatAreStoreListenersAndHowToWorkWithThemJava from './_what-are-store-listeners-and-how-to-work-with-them-java.mdx'; +import WhatAreStoreListenersAndHowToWorkWithThemCsharp from './content/_what-are-store-listeners-and-how-to-work-with-them-csharp.mdx'; +import WhatAreStoreListenersAndHowToWorkWithThemJava from './content/_what-are-store-listeners-and-how-to-work-with-them-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/net-client-versions.mdx b/versioned_docs/version-3.5/client-api/net-client-versions.mdx index 8c98e529db..61605d1b4a 100644 --- a/versioned_docs/version-3.5/client-api/net-client-versions.mdx +++ b/versioned_docs/version-3.5/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-3.5/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-3.5/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index fcb5b3dd1d..ece2d33b1f 100644 --- a/versioned_docs/version-3.5/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-3.5/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-3.5/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 971a61f3fc..cdeebd7e41 100644 --- a/versioned_docs/version-3.5/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-3.5/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-3.5/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-3.5/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-3.5/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/deleting-entities.mdx b/versioned_docs/version-3.5/client-api/session/deleting-entities.mdx index b2a387fd2b..9b35690fb0 100644 --- a/versioned_docs/version-3.5/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-3.5/client-api/session/deleting-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-3.5/client-api/session/how-to/check-if-entity-has-changed.mdx index d4312b3f1d..f100e72b8e 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-3.5/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index aed985225e..4667c7cf4e 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-3.5/client-api/session/how-to/clear-a-session.mdx index e0f42b1690..dc776c029f 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/clear-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-etag-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-etag-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-etag-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-etag-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-etag-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-etag-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-etag-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-etag-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-metadata-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-metadata-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-metadata-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-metadata-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-metadata-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-url-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-url-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-url-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-url-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_get-entity-url-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-url-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_get-entity-url-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_get-entity-url-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_mark-entity-as-readonly-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_mark-entity-as-readonly-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_mark-entity-as-readonly-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_mark-entity-as-readonly-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_mark-entity-as-readonly-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_mark-entity-as-readonly-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_mark-entity-as-readonly-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_mark-entity-as-readonly-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_perform-operations-lazily-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_perform-operations-lazily-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_perform-operations-lazily-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_perform-operations-lazily-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_use-morelikethis-csharp.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_use-morelikethis-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/_use-morelikethis-java.mdx b/versioned_docs/version-3.5/client-api/session/how-to/content/_use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/how-to/_use-morelikethis-java.mdx rename to versioned_docs/version-3.5/client-api/session/how-to/content/_use-morelikethis-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-3.5/client-api/session/how-to/defer-operations.mdx index b0aba07bd7..d3c8837b64 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-3.5/client-api/session/how-to/evict-entity-from-a-session.mdx index 9a908c6884..7421ee87f4 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-etag.mdx b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-etag.mdx index 496a20c047..e348419dde 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-etag.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-etag.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityEtagCsharp from './_get-entity-etag-csharp.mdx'; -import GetEntityEtagJava from './_get-entity-etag-java.mdx'; +import GetEntityEtagCsharp from './content/_get-entity-etag-csharp.mdx'; +import GetEntityEtagJava from './content/_get-entity-etag-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-id.mdx index 164c11f2c6..4bc64cc539 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-id.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-metadata.mdx b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-metadata.mdx index fceb8bde14..f5ef9f96fd 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-metadata.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-metadata.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityMetadataCsharp from './_get-entity-metadata-csharp.mdx'; -import GetEntityMetadataJava from './_get-entity-metadata-java.mdx'; +import GetEntityMetadataCsharp from './content/_get-entity-metadata-csharp.mdx'; +import GetEntityMetadataJava from './content/_get-entity-metadata-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-url.mdx b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-url.mdx index 291fd667bd..068ed6faf2 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/get-entity-url.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/get-entity-url.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityUrlCsharp from './_get-entity-url-csharp.mdx'; -import GetEntityUrlJava from './_get-entity-url-java.mdx'; +import GetEntityUrlCsharp from './content/_get-entity-url-csharp.mdx'; +import GetEntityUrlJava from './content/_get-entity-url-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/mark-entity-as-readonly.mdx b/versioned_docs/version-3.5/client-api/session/how-to/mark-entity-as-readonly.mdx index 606dc417ea..236adf2ef3 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/mark-entity-as-readonly.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/mark-entity-as-readonly.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MarkEntityAsReadonlyCsharp from './_mark-entity-as-readonly-csharp.mdx'; -import MarkEntityAsReadonlyJava from './_mark-entity-as-readonly-java.mdx'; +import MarkEntityAsReadonlyCsharp from './content/_mark-entity-as-readonly-csharp.mdx'; +import MarkEntityAsReadonlyJava from './content/_mark-entity-as-readonly-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-3.5/client-api/session/how-to/perform-operations-lazily.mdx index 5511326bef..986f73f7f4 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyJava from './_perform-operations-lazily-java.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyJava from './content/_perform-operations-lazily-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-3.5/client-api/session/how-to/refresh-entity.mdx index 3e1fbc36fa..d8e9b9aa3d 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/refresh-entity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/how-to/use-morelikethis.mdx b/versioned_docs/version-3.5/client-api/session/how-to/use-morelikethis.mdx index edeb1c556d..21b45430cb 100644 --- a/versioned_docs/version-3.5/client-api/session/how-to/use-morelikethis.mdx +++ b/versioned_docs/version-3.5/client-api/session/how-to/use-morelikethis.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseMorelikethisCsharp from './_use-morelikethis-csharp.mdx'; -import UseMorelikethisJava from './_use-morelikethis-java.mdx'; +import UseMorelikethisCsharp from './content/_use-morelikethis-csharp.mdx'; +import UseMorelikethisJava from './content/_use-morelikethis-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/loading-entities.mdx b/versioned_docs/version-3.5/client-api/session/loading-entities.mdx index b6a7e9dbfa..b200993e6c 100644 --- a/versioned_docs/version-3.5/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-3.5/client-api/session/loading-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/opening-a-session.mdx b/versioned_docs/version-3.5/client-api/session/opening-a-session.mdx index e01e531ad0..e77a7a419b 100644 --- a/versioned_docs/version-3.5/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-3.5/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-multifaceted-search-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-multifaceted-search-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-multifaceted-search-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-a-multifaceted-search-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-a-multifaceted-search-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-dynamic-aggregation-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-dynamic-aggregation-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-dynamic-aggregation-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-dynamic-aggregation-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-dynamic-aggregation-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-projection-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-projection-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-projection-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-projection-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-projection-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-projection-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-projection-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-projection-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-query-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-query-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-query-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-search-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-search-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-search-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-search-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-transformers-in-queries-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-transformers-in-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-transformers-in-queries-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-transformers-in-queries-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-use-transformers-in-queries-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-transformers-in-queries-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-use-transformers-in-queries-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-use-transformers-in-queries-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-customize-query.mdx index 62d4da6902..3341c59a3f 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-customize-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-get-query-statistics.mdx index 94718125d1..3c036f0714 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-faceted-search.mdx index a8ca5cd841..4e9386e3e2 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx index a71b58451a..61b934ca0e 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-a-multifaceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAMultifacetedSearchCsharp from './_how-to-perform-a-multifaceted-search-csharp.mdx'; -import HowToPerformAMultifacetedSearchJava from './_how-to-perform-a-multifaceted-search-java.mdx'; +import HowToPerformAMultifacetedSearchCsharp from './content/_how-to-perform-a-multifaceted-search-csharp.mdx'; +import HowToPerformAMultifacetedSearchJava from './content/_how-to-perform-a-multifaceted-search-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx index 0a3e1ad54b..fbc60ddfcb 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-dynamic-aggregation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformDynamicAggregationCsharp from './_how-to-perform-dynamic-aggregation-csharp.mdx'; -import HowToPerformDynamicAggregationJava from './_how-to-perform-dynamic-aggregation-java.mdx'; +import HowToPerformDynamicAggregationCsharp from './content/_how-to-perform-dynamic-aggregation-csharp.mdx'; +import HowToPerformDynamicAggregationJava from './content/_how-to-perform-dynamic-aggregation-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-projection.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-projection.mdx index 6ab93ad467..16828a1831 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-projection.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-projection.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProjectionCsharp from './_how-to-perform-projection-csharp.mdx'; -import HowToPerformProjectionJava from './_how-to-perform-projection-java.mdx'; +import HowToPerformProjectionCsharp from './content/_how-to-perform-projection-csharp.mdx'; +import HowToPerformProjectionJava from './content/_how-to-perform-projection-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-queries-lazily.mdx index e5f0b90037..478337c56f 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-query-a-spatial-index.mdx index 1811c4b2aa..194ffede17 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-query.mdx index c46ccff1b8..9ee79db66c 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryJava from './_how-to-query-java.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryJava from './content/_how-to-query-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-stream-query-results.mdx index eddda14f7e..c30d388a07 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-highlighting.mdx index 94b03e2b95..b501af271c 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-intersect.mdx index bd059a2608..710a04f0cf 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-intersect.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-search.mdx index 61347b249c..e0b6197771 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; -import HowToUseSearchJava from './_how-to-use-search-java.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; +import HowToUseSearchJava from './content/_how-to-use-search-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-transformers-in-queries.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-transformers-in-queries.mdx index f345d016a5..5e14b3817c 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-use-transformers-in-queries.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-use-transformers-in-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseTransformersInQueriesCsharp from './_how-to-use-transformers-in-queries-csharp.mdx'; -import HowToUseTransformersInQueriesJava from './_how-to-use-transformers-in-queries-java.mdx'; +import HowToUseTransformersInQueriesCsharp from './content/_how-to-use-transformers-in-queries-csharp.mdx'; +import HowToUseTransformersInQueriesJava from './content/_how-to-use-transformers-in-queries-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-3.5/client-api/session/querying/how-to-work-with-suggestions.mdx index 19770b6e7a..cbb8118d39 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-lucene-in-queries-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-lucene-in-queries-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-not-operator-java.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-3.5/client-api/session/querying/lucene/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-3.5/client-api/session/querying/lucene/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx index 623d2ba14b..b32205af4e 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-lucene-in-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneInQueriesCsharp from './_how-to-use-lucene-in-queries-csharp.mdx'; -import HowToUseLuceneInQueriesJava from './_how-to-use-lucene-in-queries-java.mdx'; +import HowToUseLuceneInQueriesCsharp from './content/_how-to-use-lucene-in-queries-csharp.mdx'; +import HowToUseLuceneInQueriesJava from './content/_how-to-use-lucene-in-queries-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-not-operator.mdx b/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-not-operator.mdx index 007cfe87b7..5ea970d99a 100644 --- a/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-not-operator.mdx +++ b/versioned_docs/version-3.5/client-api/session/querying/lucene/how-to-use-not-operator.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/saving-changes.mdx b/versioned_docs/version-3.5/client-api/session/saving-changes.mdx index d6eb790444..94a1964999 100644 --- a/versioned_docs/version-3.5/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-3.5/client-api/session/saving-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/storing-entities.mdx b/versioned_docs/version-3.5/client-api/session/storing-entities.mdx index c65914af09..a17691ac86 100644 --- a/versioned_docs/version-3.5/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-3.5/client-api/session/storing-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-3.5/client-api/session/what-is-a-session-and-how-does-it-work.mdx index f1b3580240..88123ae524 100644 --- a/versioned_docs/version-3.5/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-3.5/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/setting-up-connection-string.mdx b/versioned_docs/version-3.5/client-api/setting-up-connection-string.mdx index d174b93ec6..1a4f066af0 100644 --- a/versioned_docs/version-3.5/client-api/setting-up-connection-string.mdx +++ b/versioned_docs/version-3.5/client-api/setting-up-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpConnectionStringCsharp from './_setting-up-connection-string-csharp.mdx'; -import SettingUpConnectionStringJava from './_setting-up-connection-string-java.mdx'; +import SettingUpConnectionStringCsharp from './content/_setting-up-connection-string-csharp.mdx'; +import SettingUpConnectionStringJava from './content/_setting-up-connection-string-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/setting-up-default-database.mdx b/versioned_docs/version-3.5/client-api/setting-up-default-database.mdx index f42e60e512..50fe3a0709 100644 --- a/versioned_docs/version-3.5/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-3.5/client-api/setting-up-default-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; diff --git a/versioned_docs/version-3.5/client-api/what-is-a-document-store.mdx b/versioned_docs/version-3.5/client-api/what-is-a-document-store.mdx index d197224f3c..d35f2153fb 100644 --- a/versioned_docs/version-3.5/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-3.5/client-api/what-is-a-document-store.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-configuration-changes-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-configuration-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-configuration-changes-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-configuration-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-conflicts-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-conflicts-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-conflicts-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-conflicts-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-file-changes-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-file-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-file-changes-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-file-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-synchronization-notifications-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-synchronization-notifications-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/changes/_how-to-subscribe-synchronization-notifications-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/changes/content/_how-to-subscribe-synchronization-notifications-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx index 9de2861884..1a48144a97 100644 --- a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-configuration-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeConfigurationChangesCsharp from './_how-to-subscribe-configuration-changes-csharp.mdx'; +import HowToSubscribeConfigurationChangesCsharp from './content/_how-to-subscribe-configuration-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-conflicts.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-conflicts.mdx index 934d9b78aa..26f11b695d 100644 --- a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-conflicts.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-conflicts.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeConflictsCsharp from './_how-to-subscribe-conflicts-csharp.mdx'; +import HowToSubscribeConflictsCsharp from './content/_how-to-subscribe-conflicts-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-file-changes.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-file-changes.mdx index c00c28578b..89813e17a4 100644 --- a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-file-changes.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-file-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeFileChangesCsharp from './_how-to-subscribe-file-changes-csharp.mdx'; +import HowToSubscribeFileChangesCsharp from './content/_how-to-subscribe-file-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx index 0a34f512f7..8d78280972 100644 --- a/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/changes/how-to-subscribe-synchronization-notifications.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeSynchronizationNotificationsCsharp from './_how-to-subscribe-synchronization-notifications-csharp.mdx'; +import HowToSubscribeSynchronizationNotificationsCsharp from './content/_how-to-subscribe-synchronization-notifications-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/backup-restore.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/backup-restore.mdx index 4808d86d27..5488e6ef1d 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/admin/backup-restore.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/admin/backup-restore.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BackupRestoreCsharp from './_backup-restore-csharp.mdx'; -import BackupRestoreHttp from './_backup-restore-http.mdx'; +import BackupRestoreCsharp from './content/_backup-restore-csharp.mdx'; +import BackupRestoreHttp from './content/_backup-restore-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/compaction.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/compaction.mdx index 33a7b036e7..5fc6e09762 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/admin/compaction.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/admin/compaction.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactionCsharp from './_compaction-csharp.mdx'; -import CompactionHttp from './_compaction-http.mdx'; +import CompactionCsharp from './content/_compaction-csharp.mdx'; +import CompactionHttp from './content/_compaction-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_backup-restore-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_backup-restore-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_backup-restore-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_backup-restore-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_backup-restore-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_backup-restore-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_backup-restore-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_backup-restore-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_compaction-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_compaction-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_compaction-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_compaction-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_compaction-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_compaction-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_compaction-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_compaction-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_manage-filesystems-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_manage-filesystems-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_manage-filesystems-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_manage-filesystems-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_manage-filesystems-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_manage-filesystems-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_manage-filesystems-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_manage-filesystems-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_reset-indexes-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_reset-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_reset-indexes-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_reset-indexes-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_reset-indexes-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_reset-indexes-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_reset-indexes-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_reset-indexes-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_stats-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_stats-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_stats-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_stats-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/_stats-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_stats-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/admin/_stats-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/admin/content/_stats-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/manage-filesystems.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/manage-filesystems.mdx index 98ae468d53..710a4b73fa 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/admin/manage-filesystems.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/admin/manage-filesystems.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ManageFilesystemsCsharp from './_manage-filesystems-csharp.mdx'; -import ManageFilesystemsHttp from './_manage-filesystems-http.mdx'; +import ManageFilesystemsCsharp from './content/_manage-filesystems-csharp.mdx'; +import ManageFilesystemsHttp from './content/_manage-filesystems-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/reset-indexes.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/reset-indexes.mdx index b13038f3ed..a66f1f1f05 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/admin/reset-indexes.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/admin/reset-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexesCsharp from './_reset-indexes-csharp.mdx'; -import ResetIndexesHttp from './_reset-indexes-http.mdx'; +import ResetIndexesCsharp from './content/_reset-indexes-csharp.mdx'; +import ResetIndexesHttp from './content/_reset-indexes-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/admin/stats.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/admin/stats.mdx index 70f5d56c83..debdbdb71b 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/admin/stats.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/admin/stats.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StatsCsharp from './_stats-csharp.mdx'; -import StatsHttp from './_stats-http.mdx'; +import StatsCsharp from './content/_stats-csharp.mdx'; +import StatsHttp from './content/_stats-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_delete-key-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_delete-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_delete-key-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_delete-key-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_delete-key-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_delete-key-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_delete-key-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_delete-key-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-names-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-names-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-names-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-names-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-names-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-names-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_get-key-names-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_get-key-names-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_search-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_search-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_search-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_search-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_search-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_search-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_search-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_search-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_set-key-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_set-key-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_set-key-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_set-key-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/_set-key-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_set-key-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/configurations/_set-key-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/configurations/content/_set-key-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/delete-key.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/delete-key.mdx index ec8dfe0637..6d1f8fdfba 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/delete-key.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/delete-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteKeyCsharp from './_delete-key-csharp.mdx'; -import DeleteKeyHttp from './_delete-key-http.mdx'; +import DeleteKeyCsharp from './content/_delete-key-csharp.mdx'; +import DeleteKeyHttp from './content/_delete-key-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key-names.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key-names.mdx index 87978489cc..c1e5098406 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key-names.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetKeyNamesCsharp from './_get-key-names-csharp.mdx'; -import GetKeyNamesHttp from './_get-key-names-http.mdx'; +import GetKeyNamesCsharp from './content/_get-key-names-csharp.mdx'; +import GetKeyNamesHttp from './content/_get-key-names-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key.mdx index 26966d811b..78942b0f5a 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/get-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetKeyCsharp from './_get-key-csharp.mdx'; -import GetKeyHttp from './_get-key-http.mdx'; +import GetKeyCsharp from './content/_get-key-csharp.mdx'; +import GetKeyHttp from './content/_get-key-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/search.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/search.mdx index 0de55710d2..4960e64d8e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/search.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchCsharp from './_search-csharp.mdx'; -import SearchHttp from './_search-http.mdx'; +import SearchCsharp from './content/_search-csharp.mdx'; +import SearchHttp from './content/_search-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/set-key.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/set-key.mdx index 9f1939f711..82b93f5b00 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/configurations/set-key.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/configurations/set-key.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetKeyCsharp from './_set-key-csharp.mdx'; -import SetKeyHttp from './_set-key-http.mdx'; +import SetKeyCsharp from './content/_set-key-csharp.mdx'; +import SetKeyHttp from './content/_set-key-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/browse-overview.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/browse-overview.mdx index 3d2dcb9986..7ce3021f72 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/browse-overview.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/browse-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BrowseOverviewCsharp from './_browse-overview-csharp.mdx'; -import BrowseOverviewHttp from './_browse-overview-http.mdx'; +import BrowseOverviewCsharp from './content/_browse-overview-csharp.mdx'; +import BrowseOverviewHttp from './content/_browse-overview-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_browse-overview-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_browse-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_browse-overview-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_browse-overview-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_browse-overview-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_browse-overview-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_browse-overview-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_browse-overview-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-directories-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-directories-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-directories-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-directories-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-directories-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-directories-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-directories-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-directories-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_get-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_starts-with-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_starts-with-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_starts-with-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_starts-with-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_starts-with-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_starts-with-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_starts-with-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_starts-with-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-file-headers-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-file-headers-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-file-headers-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-file-headers-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-file-headers-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-file-headers-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-file-headers-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-file-headers-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-query-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/browse/_stream-query-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/browse/content/_stream-query-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get-directories.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get-directories.mdx index c38acd0f6a..177ef3258c 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get-directories.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get-directories.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDirectoriesCsharp from './_get-directories-csharp.mdx'; -import GetDirectoriesHttp from './_get-directories-http.mdx'; +import GetDirectoriesCsharp from './content/_get-directories-csharp.mdx'; +import GetDirectoriesHttp from './content/_get-directories-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get.mdx index 74ca6b09ff..4b7e7f2a4a 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/starts-with.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/starts-with.mdx index 7f86d86fd4..65f0850649 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/starts-with.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/starts-with.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithCsharp from './_starts-with-csharp.mdx'; -import StartsWithHttp from './_starts-with-http.mdx'; +import StartsWithCsharp from './content/_starts-with-csharp.mdx'; +import StartsWithHttp from './content/_starts-with-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-file-headers.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-file-headers.mdx index 9d4f69627a..f2716459d8 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-file-headers.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-file-headers.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamFileHeadersCsharp from './_stream-file-headers-csharp.mdx'; -import StreamFileHeadersHttp from './_stream-file-headers-http.mdx'; +import StreamFileHeadersCsharp from './content/_stream-file-headers-csharp.mdx'; +import StreamFileHeadersHttp from './content/_stream-file-headers-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-query.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-query.mdx index 0be2d85c59..f125c48708 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-query.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/browse/stream-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryCsharp from './_stream-query-csharp.mdx'; +import StreamQueryCsharp from './content/_stream-query-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_copy-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_copy-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_copy-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_copy-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_delete-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_delete-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_delete-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_delete-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_delete-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_delete-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_delete-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_download-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_download-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_download-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_download-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_download-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_download-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_download-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_download-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_rename-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_rename-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_rename-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_rename-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_rename-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_rename-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_rename-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_rename-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_upload-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_upload-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_upload-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_upload-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/_upload-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/content/_upload-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/_upload-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/content/_upload-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/copy.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/copy.mdx index 1dbe9eba46..4866d78146 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/copy.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/copy.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyCsharp from './_copy-csharp.mdx'; +import CopyCsharp from './content/_copy-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/delete.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/delete.mdx index 8b8910cd58..ddee33f8df 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/delete.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteHttp from './_delete-http.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteHttp from './content/_delete-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/download.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/download.mdx index 5ee6e63734..9179c7ef7a 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/download.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/download.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DownloadCsharp from './_download-csharp.mdx'; -import DownloadHttp from './_download-http.mdx'; +import DownloadCsharp from './content/_download-csharp.mdx'; +import DownloadHttp from './content/_download-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_get-metadata-for-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_get-metadata-for-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_get-metadata-for-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_get-metadata-for-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_get-metadata-for-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_get-metadata-for-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_get-metadata-for-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_get-metadata-for-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_update-metadata-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_update-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_update-metadata-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_update-metadata-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_update-metadata-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_update-metadata-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/_update-metadata-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/content/_update-metadata-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/get-metadata-for.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/get-metadata-for.mdx index 24b11cbbdc..139f80138b 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/get-metadata-for.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/get-metadata-for.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetMetadataForCsharp from './_get-metadata-for-csharp.mdx'; -import GetMetadataForHttp from './_get-metadata-for-http.mdx'; +import GetMetadataForCsharp from './content/_get-metadata-for-csharp.mdx'; +import GetMetadataForHttp from './content/_get-metadata-for-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/update-metadata.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/update-metadata.mdx index 6171ce317f..79fe48781e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/update-metadata.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/metadata/update-metadata.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateMetadataCsharp from './_update-metadata-csharp.mdx'; -import UpdateMetadataHttp from './_update-metadata-http.mdx'; +import UpdateMetadataCsharp from './content/_update-metadata-csharp.mdx'; +import UpdateMetadataHttp from './content/_update-metadata-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/rename.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/rename.mdx index 33fd2da641..b6e095a91e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/rename.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/rename.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RenameCsharp from './_rename-csharp.mdx'; -import RenameHttp from './_rename-http.mdx'; +import RenameCsharp from './content/_rename-csharp.mdx'; +import RenameHttp from './content/_rename-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_get-search-fields-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_get-search-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_get-search-fields-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_get-search-fields-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_get-search-fields-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_get-search-fields-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_get-search-fields-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_get-search-fields-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-on-directory-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-on-directory-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-on-directory-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-on-directory-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-on-directory-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-on-directory-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-on-directory-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-on-directory-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-overview-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-overview-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-overview-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-overview-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-overview-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/files/search/_search-overview-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/files/search/content/_search-overview-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/get-search-fields.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/get-search-fields.mdx index d0a50bb238..ad4781c9ee 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/get-search-fields.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/get-search-fields.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetSearchFieldsCsharp from './_get-search-fields-csharp.mdx'; -import GetSearchFieldsHttp from './_get-search-fields-http.mdx'; +import GetSearchFieldsCsharp from './content/_get-search-fields-csharp.mdx'; +import GetSearchFieldsHttp from './content/_get-search-fields-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-on-directory.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-on-directory.mdx index be2f224032..fbf839babc 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-on-directory.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-on-directory.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchOnDirectoryCsharp from './_search-on-directory-csharp.mdx'; -import SearchOnDirectoryHttp from './_search-on-directory-http.mdx'; +import SearchOnDirectoryCsharp from './content/_search-on-directory-csharp.mdx'; +import SearchOnDirectoryHttp from './content/_search-on-directory-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-overview.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-overview.mdx index b95fbba7f8..d2559b8f66 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-overview.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/search/search-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchOverviewCsharp from './_search-overview-csharp.mdx'; -import SearchOverviewHttp from './_search-overview-http.mdx'; +import SearchOverviewCsharp from './content/_search-overview-csharp.mdx'; +import SearchOverviewHttp from './content/_search-overview-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/files/upload.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/files/upload.mdx index ad33ec9bee..3fb0f86a48 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/files/upload.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/files/upload.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UploadCsharp from './_upload-csharp.mdx'; -import UploadHttp from './_upload-http.mdx'; +import UploadCsharp from './content/_upload-csharp.mdx'; +import UploadHttp from './content/_upload-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/cleanup.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/cleanup.mdx index 3f765f46b5..95064c4ab8 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/storage/cleanup.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/storage/cleanup.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CleanupCsharp from './_cleanup-csharp.mdx'; -import CleanupHttp from './_cleanup-http.mdx'; +import CleanupCsharp from './content/_cleanup-csharp.mdx'; +import CleanupHttp from './content/_cleanup-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/_cleanup-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_cleanup-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/storage/_cleanup-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_cleanup-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/_cleanup-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_cleanup-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/storage/_cleanup-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_cleanup-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/_retry-renaming-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_retry-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/storage/_retry-renaming-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_retry-renaming-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/_retry-renaming-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_retry-renaming-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/storage/_retry-renaming-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/storage/content/_retry-renaming-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/storage/retry-renaming.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/storage/retry-renaming.mdx index d1fdd6f241..329dbccfef 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/storage/retry-renaming.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/storage/retry-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetryRenamingCsharp from './_retry-renaming-csharp.mdx'; -import RetryRenamingHttp from './_retry-renaming-http.mdx'; +import RetryRenamingCsharp from './content/_retry-renaming-csharp.mdx'; +import RetryRenamingHttp from './content/_retry-renaming-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_get-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_get-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_get-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_get-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_resolve-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_resolve-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_resolve-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_resolve-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_resolve-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_resolve-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/_resolve-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/content/_resolve-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/get.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/get.mdx index a739024ad8..85be44500e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/get.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/resolve.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/resolve.mdx index 3a02cd3c7a..ef8586ac99 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/resolve.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/conflicts/resolve.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResolveCsharp from './_resolve-csharp.mdx'; -import ResolveHttp from './_resolve-http.mdx'; +import ResolveCsharp from './content/_resolve-csharp.mdx'; +import ResolveHttp from './content/_resolve-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/_start-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/content/_start-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/_start-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/content/_start-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/_start-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/content/_start-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/_start-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/content/_start-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_get-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_get-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_get-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_get-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_get-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_get-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_get-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_set-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_set-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_set-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_set-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_set-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_set-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/_set-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/content/_set-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/get.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/get.mdx index 6b6268ff59..3a8a714b8b 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/get.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetHttp from './_get-http.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetHttp from './content/_get-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/set.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/set.mdx index 35bdf80e7c..e29620fc2e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/set.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/destinations/set.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetCsharp from './_set-csharp.mdx'; -import SetHttp from './_set-http.mdx'; +import SetCsharp from './content/_set-csharp.mdx'; +import SetHttp from './content/_set-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/active.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/active.mdx index 1b8425e292..1808cd52d5 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/active.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/active.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ActiveCsharp from './_active-csharp.mdx'; -import ActiveHttp from './_active-http.mdx'; +import ActiveCsharp from './content/_active-csharp.mdx'; +import ActiveHttp from './content/_active-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_active-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_active-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_active-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_active-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_active-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_active-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_active-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_active-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_finished-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_finished-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_finished-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_finished-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_finished-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_finished-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_finished-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_finished-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_pending-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_pending-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_pending-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_pending-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_pending-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_pending-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_pending-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_pending-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_status-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_status-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_status-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_status-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_status-http.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_status-http.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/_status-http.mdx rename to versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/content/_status-http.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/finished.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/finished.mdx index f85ebf773c..87cce1bb82 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/finished.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/finished.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FinishedCsharp from './_finished-csharp.mdx'; -import FinishedHttp from './_finished-http.mdx'; +import FinishedCsharp from './content/_finished-csharp.mdx'; +import FinishedHttp from './content/_finished-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/pending.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/pending.mdx index c163bcb09e..6a9f301325 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/pending.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/pending.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PendingCsharp from './_pending-csharp.mdx'; -import PendingHttp from './_pending-http.mdx'; +import PendingCsharp from './content/_pending-csharp.mdx'; +import PendingHttp from './content/_pending-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/status.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/status.mdx index e3998c108b..7888601f1e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/status.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/monitoring/status.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StatusCsharp from './_status-csharp.mdx'; -import StatusHttp from './_status-http.mdx'; +import StatusCsharp from './content/_status-csharp.mdx'; +import StatusHttp from './content/_status-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/start.mdx b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/start.mdx index e59549e606..a4f685b3d4 100644 --- a/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/start.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/commands/synchronization/start.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "http"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartCsharp from './_start-csharp.mdx'; -import StartHttp from './_start-http.mdx'; +import StartCsharp from './content/_start-csharp.mdx'; +import StartHttp from './content/_start-http.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/conflict-listeners.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/conflict-listeners.mdx index 9989e68c41..e4dade289b 100644 --- a/versioned_docs/version-3.5/file-system/client-api/listeners/conflict-listeners.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/listeners/conflict-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictListenersCsharp from './_conflict-listeners-csharp.mdx'; +import ConflictListenersCsharp from './content/_conflict-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/_conflict-listeners-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/content/_conflict-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/listeners/_conflict-listeners-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/listeners/content/_conflict-listeners-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/_delete-listeners-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/content/_delete-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/listeners/_delete-listeners-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/listeners/content/_delete-listeners-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/_metadata-change-listeners-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/content/_metadata-change-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/listeners/_metadata-change-listeners-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/listeners/content/_metadata-change-listeners-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/_what-are-listeners-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/content/_what-are-listeners-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/listeners/_what-are-listeners-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/listeners/content/_what-are-listeners-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/delete-listeners.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/delete-listeners.mdx index 3bb78eebd4..45c5e64dd2 100644 --- a/versioned_docs/version-3.5/file-system/client-api/listeners/delete-listeners.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/listeners/delete-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteListenersCsharp from './_delete-listeners-csharp.mdx'; +import DeleteListenersCsharp from './content/_delete-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/metadata-change-listeners.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/metadata-change-listeners.mdx index 1a7e7cb0ea..a60ad9ed9d 100644 --- a/versioned_docs/version-3.5/file-system/client-api/listeners/metadata-change-listeners.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/listeners/metadata-change-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MetadataChangeListenersCsharp from './_metadata-change-listeners-csharp.mdx'; +import MetadataChangeListenersCsharp from './content/_metadata-change-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/listeners/what-are-listeners.mdx b/versioned_docs/version-3.5/file-system/client-api/listeners/what-are-listeners.mdx index 8e1cf29c80..b84b4988cd 100644 --- a/versioned_docs/version-3.5/file-system/client-api/listeners/what-are-listeners.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/listeners/what-are-listeners.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreListenersCsharp from './_what-are-listeners-csharp.mdx'; +import WhatAreListenersCsharp from './content/_what-are-listeners-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/changing-metadata.mdx b/versioned_docs/version-3.5/file-system/client-api/session/changing-metadata.mdx index 5128af61a9..556a15ad89 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/changing-metadata.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/changing-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChangingMetadataCsharp from './_changing-metadata-csharp.mdx'; +import ChangingMetadataCsharp from './content/_changing-metadata-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 7de0106460..f66af9eeb1 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 5b9072b439..68f2c78859 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_changing-metadata-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_changing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_changing-metadata-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_changing-metadata-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_deleting-files-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_deleting-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_deleting-files-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_deleting-files-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_downloading-files-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_downloading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_downloading-files-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_downloading-files-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_loading-files-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_loading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_loading-files-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_loading-files-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_opening-session-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_opening-session-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_opening-session-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_opening-session-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_renaming-files-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_renaming-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_renaming-files-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_renaming-files-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/_uploading-files-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/content/_uploading-files-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/_uploading-files-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/content/_uploading-files-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/deleting-files.mdx b/versioned_docs/version-3.5/file-system/client-api/session/deleting-files.mdx index 064efea10f..3a052692a7 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/deleting-files.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/deleting-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingFilesCsharp from './_deleting-files-csharp.mdx'; +import DeletingFilesCsharp from './content/_deleting-files-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/downloading-files.mdx b/versioned_docs/version-3.5/file-system/client-api/session/downloading-files.mdx index d5c3eff227..8fd942a1d5 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/downloading-files.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/downloading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DownloadingFilesCsharp from './_downloading-files-csharp.mdx'; +import DownloadingFilesCsharp from './content/_downloading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/loading-files.mdx b/versioned_docs/version-3.5/file-system/client-api/session/loading-files.mdx index 272febc243..a04fa34057 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/loading-files.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/loading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingFilesCsharp from './_loading-files-csharp.mdx'; +import LoadingFilesCsharp from './content/_loading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/opening-session.mdx b/versioned_docs/version-3.5/file-system/client-api/session/opening-session.mdx index 403c39250b..b94277df52 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/opening-session.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/opening-session.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningSessionCsharp from './_opening-session-csharp.mdx'; +import OpeningSessionCsharp from './content/_opening-session-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/basics.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/basics.mdx index cbf2f57cef..48c22818d3 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/basics.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/basics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_basics-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_basics-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_filtering-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_filtering-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_paging-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_paging-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_paging-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_paging-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_sorting-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_sorting-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_statistics-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_statistics-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_statistics-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/_streaming-csharp.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/content/_streaming-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/file-system/client-api/session/querying/_streaming-csharp.mdx rename to versioned_docs/version-3.5/file-system/client-api/session/querying/content/_streaming-csharp.mdx diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/filtering.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/filtering.mdx index df25fac6b5..b7aa321a46 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/filtering.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/filtering.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/paging.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/paging.mdx index a064254d94..03776c36ab 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/paging.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/paging.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/sorting.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/sorting.mdx index bfe3b5ddf8..031f5338ad 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/sorting.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/sorting.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/statistics.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/statistics.mdx index 7480b57fb2..6c58f64a2b 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/statistics.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StatisticsCsharp from './_statistics-csharp.mdx'; +import StatisticsCsharp from './content/_statistics-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/querying/streaming.mdx b/versioned_docs/version-3.5/file-system/client-api/session/querying/streaming.mdx index 6e83b0bd26..e3a5b56e01 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/querying/streaming.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/querying/streaming.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamingCsharp from './_streaming-csharp.mdx'; +import StreamingCsharp from './content/_streaming-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/renaming-files.mdx b/versioned_docs/version-3.5/file-system/client-api/session/renaming-files.mdx index 0f3f6d240f..e51ed2952e 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/renaming-files.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/renaming-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RenamingFilesCsharp from './_renaming-files-csharp.mdx'; +import RenamingFilesCsharp from './content/_renaming-files-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/saving-changes.mdx b/versioned_docs/version-3.5/file-system/client-api/session/saving-changes.mdx index f044c77b13..241bf29e69 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/saving-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; diff --git a/versioned_docs/version-3.5/file-system/client-api/session/uploading-files.mdx b/versioned_docs/version-3.5/file-system/client-api/session/uploading-files.mdx index 628848ccd4..88c0d52694 100644 --- a/versioned_docs/version-3.5/file-system/client-api/session/uploading-files.mdx +++ b/versioned_docs/version-3.5/file-system/client-api/session/uploading-files.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UploadingFilesCsharp from './_uploading-files-csharp.mdx'; +import UploadingFilesCsharp from './content/_uploading-files-csharp.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 5b6e61bfdf..0000000000 --- a/versioned_docs/version-3.5/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -To achieve this in RavenDB, let's say you have a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against, this can be setup like so: - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Next you need to setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field look at the documents and return a count for each unique Term found -* For the **Cost** field, return the count of the following ranges: - * Cost <= 200.0 - * 200.0 <= Cost <= 400.0 - * 400.0 <= Cost <= 600.0 - * 600.0 <= Cost <= 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels <= 7.0 - * 7.0 <= Megapixels <= 10.0 - * Megapixels >= 10.0 - -## Step 3 - -Finally you can write the following code and you get back the data below: - - - - -{`FacetResults facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .ToFacets(facets); -`} - - - - -{`FacetResults facetResults = session - .Advanced - .DocumentQuery() - .WhereBetweenOrEqual(x => x.Cost, 100, 300) - .ToFacets(facets); -`} - - - - -{`FacetResults facetResults = store - .DatabaseCommands - .GetFacets( - "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery - { - Query = "Cost_Range:[Dx100 TO Dx300]" - }, - facets); -`} - - - - -{`List facets = new List -{ - new Facet - { - Name = "Manufacturer" - }, - new Facet - { - Name = x => x.Cost, - Ranges = - { - x => x.Cost < 200m, - x => x.Cost > 200m && x.Cost < 400m, - x => x.Cost > 400m && x.Cost < 600m, - x => x.Cost > 600m && x.Cost < 800m, - x => x.Cost > 800m - } - }, - new Facet - { - Name = x => x.Megapixels, - Ranges = - { - x => x.Megapixels < 3.0, - x => x.Megapixels > 3.0 && x.Megapixels < 7.0, - x => x.Megapixels > 7.0 && x.Megapixels < 10.0, - x => x.Megapixels > 10.0 - } - } -}; -`} - - - - -The data below represents the sample faceted data that satisfies above query: - - - -{`\{ - Manufacturer: [ - \{ - Range: 'canon', - Count: 42 - \}, - \{ - Range: 'jessops', - Count: 50 - \}, - \{ - Range: 'nikon', - Count: 46 - \}, - \{ - Range: 'phillips', - Count: 44 - \}, - \{ - Range: 'sony', - Count: 35 - \} - ], - Cost_Range: [ - \{ - Range: '[NULL TO Dx200.0]', - Count: 115 - \}, - \{ - Range: '[Dx200.0 TO Dx400.0]', - Count: 102 - \} - ], - Megapixels_Range: [ - \{ - Range: '[NULL TO Dx3.0]', - Count: 42 - \}, - \{ - Range: '[Dx3.0 TO Dx7.0]', - Count: 79 - \}, - \{ - Range: '[Dx7.0 TO Dx10.0]', - Count: 82 - \}, - \{ - Range: '[Dx10.0 TO NULL]', - Count: 14 - \} - ] -\} -`} - - - -### Storing facets - -Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`FacetResults facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .ToFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = session - .Advanced - .DocumentQuery() - .WhereBetweenOrEqual(x => x.Cost, 100, 300) - .ToFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = store - .DatabaseCommands - .GetFacets( - "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery - { - Query = "Cost_Range:[Dx100 TO Dx300]" - }, - "facets/CameraFacets"); -`} - - - - -{`List facets = new List -{ - new Facet - { - Name = "Manufacturer" - }, - new Facet - { - Name = x => x.Cost, - Ranges = - { - x => x.Cost < 200m, - x => x.Cost > 200m && x.Cost < 400m, - x => x.Cost > 400m && x.Cost < 600m, - x => x.Cost > 600m && x.Cost < 800m, - x => x.Cost > 800m - } - }, - new Facet - { - Name = x => x.Megapixels, - Ranges = - { - x => x.Megapixels < 3.0, - x => x.Megapixels > 3.0 && x.Megapixels < 7.0, - x => x.Megapixels > 7.0 && x.Megapixels < 10.0, - x => x.Megapixels > 10.0 - } - } -}; -`} - - - - -### Stale results - -The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `WaitForNonStaleResultsXXX` method. - - diff --git a/versioned_docs/version-3.5/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-3.5/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index b38c2e733a..0000000000 --- a/versioned_docs/version-3.5/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -To achieve this in RavenDB, let's say you have a document like this: - - - -{`public class Camera \{ - private int id; - - private Date dateOfListing; - private String manufacturer; - private String model; - private Double cost; - - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private List advancedFeatures; - - public int getId() \{ - return id; - \} - public void setId(int id) \{ - this.id = id; - \} - public Date getDateOfListing() \{ - return dateOfListing; - \} - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - public String getManufacturer() \{ - return manufacturer; - \} - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} - public String getModel() \{ - return model; - \} - public void setModel(String model) \{ - this.model = model; - \} - public Double getCost() \{ - return cost; - \} - public void setCost(Double cost) \{ - this.cost = cost; - \} - public int getZoom() \{ - return zoom; - \} - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - public double getMegapixels() \{ - return megapixels; - \} - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - public List getAdvancedFeatures() \{ - return advancedFeatures; - \} - public void setAdvancedFeatures(List advancedFeatures) \{ - this.advancedFeatures = advancedFeatures; - \} -\} -`} - - - -## Step 1 - -Create an index to work against, this can be setup like so: - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Next you need to setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field look at the documents and return a count for each unique Term found -* For the **Cost** field, return the count of the following ranges: - * Cost <= 200.0 - * 200.0 <= Cost <= 400.0 - * 400.0 <= Cost <= 600.0 - * 600.0 <= Cost <= 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels <= 7.0 - * 7.0 <= Megapixels <= 10.0 - * Megapixels >= 10.0 - -## Step 3 - -Finally you can write the following code and you get back the data below: - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .where(c.cost.goe(100).and(c.cost.loe(300))) - .toFacets(facets); -`} - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .advanced() - .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetweenOrEqual(c.cost, 100.0, 300.0) - .toFacets(facets); -`} - - - - -{`FacetResults facetResults = store - .getDatabaseCommands() - .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), - facets); -`} - - - - -{`QCamera c = QCamera.camera; - -List facets = new ArrayList<>(); -Facet f1 = new Facet(); -f1.setName(c.manufacturer); -facets.add(f1); - -Facet f2 = new Facet(); -f2.setName(c.cost); -f2.setRanges(c.cost.lt(200), - c.cost.gt(200).and(c.cost.lt(400)), - c.cost.gt(400).and(c.cost.lt(600)), - c.cost.gt(600).and(c.cost.lt(800)), - c.cost.gt(800)); -facets.add(f2); - -Facet f3 = new Facet(); -f3.setName(c.megapixels); -f3.setRanges(c.megapixels.lt(3), - c.megapixels.gt(3).and(c.megapixels.lt(7)), - c.megapixels.gt(7).and(c.megapixels.lt(10)), - c.megapixels.gt(10)); -facets.add(f3); -`} - - - - -The data below represents the sample faceted data that satisfies above query: - - - -{`\{ - Manufacturer: [ - \{ - Range: 'canon', - Count: 42 - \}, - \{ - Range: 'jessops', - Count: 50 - \}, - \{ - Range: 'nikon', - Count: 46 - \}, - \{ - Range: 'phillips', - Count: 44 - \}, - \{ - Range: 'sony', - Count: 35 - \} - ], - Cost_Range: [ - \{ - Range: '[NULL TO Dx200.0]', - Count: 115 - \}, - \{ - Range: '[Dx200.0 TO Dx400.0]', - Count: 102 - \} - ], - Megapixels_Range: [ - \{ - Range: '[NULL TO Dx3.0]', - Count: 42 - \}, - \{ - Range: '[Dx3.0 TO Dx7.0]', - Count: 79 - \}, - \{ - Range: '[Dx7.0 TO Dx10.0]', - Count: 82 - \}, - \{ - Range: '[Dx10.0 TO NULL]', - Count: 14 - \} - ] -\} -`} - - - -### Storing facets - -Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .where(c.cost.goe(100).and(c.cost.loe(300))) - .toFacets("facets/CameraFacets"); -`} - - - - -{`QCamera c = QCamera.camera; -FacetResults facetResults = session - .advanced() - .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetweenOrEqual(c.cost, 100.0, 300.0) - .toFacets("facets/CameraFacets"); -`} - - - - -{`FacetResults facetResults = store - .getDatabaseCommands() - .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", - new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), - "facets/CameraFacets"); -`} - - - - -{`QCamera c = QCamera.camera; - -List facets = new ArrayList<>(); -Facet f1 = new Facet(); -f1.setName(c.manufacturer); -facets.add(f1); - -Facet f2 = new Facet(); -f2.setName(c.cost); -f2.setRanges(c.cost.lt(200), - c.cost.gt(200).and(c.cost.lt(400)), - c.cost.gt(400).and(c.cost.lt(600)), - c.cost.gt(600).and(c.cost.lt(800)), - c.cost.gt(800)); -facets.add(f2); - -Facet f3 = new Facet(); -f3.setName(c.megapixels); -f3.setRanges(c.megapixels.lt(3), - c.megapixels.gt(3).and(c.megapixels.lt(7)), - c.megapixels.gt(7).and(c.megapixels.lt(10)), - c.megapixels.gt(10)); -facets.add(f3); -`} - - - - -### Stale results - -The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `waitForNonStaleResultsXXX` method. - - diff --git a/versioned_docs/version-3.5/indexes/querying/basics.mdx b/versioned_docs/version-3.5/indexes/querying/basics.mdx index 4a6522b0f9..42cfb4ad1a 100644 --- a/versioned_docs/version-3.5/indexes/querying/basics.mdx +++ b/versioned_docs/version-3.5/indexes/querying/basics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_basics-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_basics-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_dynamic-aggregation-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_dynamic-aggregation-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_dynamic-aggregation-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_dynamic-aggregation-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_dynamic-aggregation-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_dynamic-aggregation-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_dynamic-aggregation-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_dynamic-aggregation-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..cda61e0594 --- /dev/null +++ b/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +To achieve this in RavenDB, let's say you have a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against, this can be setup like so: + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Next you need to setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field look at the documents and return a count for each unique Term found +* For the **Cost** field, return the count of the following ranges: + * Cost <= 200.0 + * 200.0 <= Cost <= 400.0 + * 400.0 <= Cost <= 600.0 + * 600.0 <= Cost <= 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels <= 7.0 + * 7.0 <= Megapixels <= 10.0 + * Megapixels >= 10.0 + +## Step 3 + +Finally you can write the following code and you get back the data below: + + + + +{`FacetResults facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .ToFacets(facets); +`} + + + + +{`FacetResults facetResults = session + .Advanced + .DocumentQuery() + .WhereBetweenOrEqual(x => x.Cost, 100, 300) + .ToFacets(facets); +`} + + + + +{`FacetResults facetResults = store + .DatabaseCommands + .GetFacets( + "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery + { + Query = "Cost_Range:[Dx100 TO Dx300]" + }, + facets); +`} + + + + +{`List facets = new List +{ + new Facet + { + Name = "Manufacturer" + }, + new Facet + { + Name = x => x.Cost, + Ranges = + { + x => x.Cost < 200m, + x => x.Cost > 200m && x.Cost < 400m, + x => x.Cost > 400m && x.Cost < 600m, + x => x.Cost > 600m && x.Cost < 800m, + x => x.Cost > 800m + } + }, + new Facet + { + Name = x => x.Megapixels, + Ranges = + { + x => x.Megapixels < 3.0, + x => x.Megapixels > 3.0 && x.Megapixels < 7.0, + x => x.Megapixels > 7.0 && x.Megapixels < 10.0, + x => x.Megapixels > 10.0 + } + } +}; +`} + + + + +The data below represents the sample faceted data that satisfies above query: + + + +{`\{ + Manufacturer: [ + \{ + Range: 'canon', + Count: 42 + \}, + \{ + Range: 'jessops', + Count: 50 + \}, + \{ + Range: 'nikon', + Count: 46 + \}, + \{ + Range: 'phillips', + Count: 44 + \}, + \{ + Range: 'sony', + Count: 35 + \} + ], + Cost_Range: [ + \{ + Range: '[NULL TO Dx200.0]', + Count: 115 + \}, + \{ + Range: '[Dx200.0 TO Dx400.0]', + Count: 102 + \} + ], + Megapixels_Range: [ + \{ + Range: '[NULL TO Dx3.0]', + Count: 42 + \}, + \{ + Range: '[Dx3.0 TO Dx7.0]', + Count: 79 + \}, + \{ + Range: '[Dx7.0 TO Dx10.0]', + Count: 82 + \}, + \{ + Range: '[Dx10.0 TO NULL]', + Count: 14 + \} + ] +\} +`} + + + +### Storing facets + +Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`FacetResults facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .ToFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = session + .Advanced + .DocumentQuery() + .WhereBetweenOrEqual(x => x.Cost, 100, 300) + .ToFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = store + .DatabaseCommands + .GetFacets( + "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery + { + Query = "Cost_Range:[Dx100 TO Dx300]" + }, + "facets/CameraFacets"); +`} + + + + +{`List facets = new List +{ + new Facet + { + Name = "Manufacturer" + }, + new Facet + { + Name = x => x.Cost, + Ranges = + { + x => x.Cost < 200m, + x => x.Cost > 200m && x.Cost < 400m, + x => x.Cost > 400m && x.Cost < 600m, + x => x.Cost > 600m && x.Cost < 800m, + x => x.Cost > 800m + } + }, + new Facet + { + Name = x => x.Megapixels, + Ranges = + { + x => x.Megapixels < 3.0, + x => x.Megapixels > 3.0 && x.Megapixels < 7.0, + x => x.Megapixels > 7.0 && x.Megapixels < 10.0, + x => x.Megapixels > 10.0 + } + } +}; +`} + + + + +### Stale results + +The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `WaitForNonStaleResultsXXX` method. + + diff --git a/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..bffd887b33 --- /dev/null +++ b/versioned_docs/version-3.5/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, often paging is used to make viewing the data manageable. However it's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +To achieve this in RavenDB, let's say you have a document like this: + + + +{`public class Camera \{ + private int id; + + private Date dateOfListing; + private String manufacturer; + private String model; + private Double cost; + + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private List advancedFeatures; + + public int getId() \{ + return id; + \} + public void setId(int id) \{ + this.id = id; + \} + public Date getDateOfListing() \{ + return dateOfListing; + \} + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + public String getManufacturer() \{ + return manufacturer; + \} + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} + public String getModel() \{ + return model; + \} + public void setModel(String model) \{ + this.model = model; + \} + public Double getCost() \{ + return cost; + \} + public void setCost(Double cost) \{ + this.cost = cost; + \} + public int getZoom() \{ + return zoom; + \} + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + public double getMegapixels() \{ + return megapixels; + \} + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + public List getAdvancedFeatures() \{ + return advancedFeatures; + \} + public void setAdvancedFeatures(List advancedFeatures) \{ + this.advancedFeatures = advancedFeatures; + \} +\} +`} + + + +## Step 1 + +Create an index to work against, this can be setup like so: + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Next you need to setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field look at the documents and return a count for each unique Term found +* For the **Cost** field, return the count of the following ranges: + * Cost <= 200.0 + * 200.0 <= Cost <= 400.0 + * 400.0 <= Cost <= 600.0 + * 600.0 <= Cost <= 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels <= 7.0 + * 7.0 <= Megapixels <= 10.0 + * Megapixels >= 10.0 + +## Step 3 + +Finally you can write the following code and you get back the data below: + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .where(c.cost.goe(100).and(c.cost.loe(300))) + .toFacets(facets); +`} + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .advanced() + .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetweenOrEqual(c.cost, 100.0, 300.0) + .toFacets(facets); +`} + + + + +{`FacetResults facetResults = store + .getDatabaseCommands() + .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), + facets); +`} + + + + +{`QCamera c = QCamera.camera; + +List facets = new ArrayList<>(); +Facet f1 = new Facet(); +f1.setName(c.manufacturer); +facets.add(f1); + +Facet f2 = new Facet(); +f2.setName(c.cost); +f2.setRanges(c.cost.lt(200), + c.cost.gt(200).and(c.cost.lt(400)), + c.cost.gt(400).and(c.cost.lt(600)), + c.cost.gt(600).and(c.cost.lt(800)), + c.cost.gt(800)); +facets.add(f2); + +Facet f3 = new Facet(); +f3.setName(c.megapixels); +f3.setRanges(c.megapixels.lt(3), + c.megapixels.gt(3).and(c.megapixels.lt(7)), + c.megapixels.gt(7).and(c.megapixels.lt(10)), + c.megapixels.gt(10)); +facets.add(f3); +`} + + + + +The data below represents the sample faceted data that satisfies above query: + + + +{`\{ + Manufacturer: [ + \{ + Range: 'canon', + Count: 42 + \}, + \{ + Range: 'jessops', + Count: 50 + \}, + \{ + Range: 'nikon', + Count: 46 + \}, + \{ + Range: 'phillips', + Count: 44 + \}, + \{ + Range: 'sony', + Count: 35 + \} + ], + Cost_Range: [ + \{ + Range: '[NULL TO Dx200.0]', + Count: 115 + \}, + \{ + Range: '[Dx200.0 TO Dx400.0]', + Count: 102 + \} + ], + Megapixels_Range: [ + \{ + Range: '[NULL TO Dx3.0]', + Count: 42 + \}, + \{ + Range: '[Dx3.0 TO Dx7.0]', + Count: 79 + \}, + \{ + Range: '[Dx7.0 TO Dx10.0]', + Count: 82 + \}, + \{ + Range: '[Dx10.0 TO NULL]', + Count: 14 + \} + ] +\} +`} + + + +### Storing facets + +Alternatively, if you do not have to change your facets dynamically, you can store your facets as `FacetSetup` document and pass the document Id instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .where(c.cost.goe(100).and(c.cost.loe(300))) + .toFacets("facets/CameraFacets"); +`} + + + + +{`QCamera c = QCamera.camera; +FacetResults facetResults = session + .advanced() + .documentQuery(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetweenOrEqual(c.cost, 100.0, 300.0) + .toFacets("facets/CameraFacets"); +`} + + + + +{`FacetResults facetResults = store + .getDatabaseCommands() + .getFacets("Cameras/ByManufacturerModelCostDateOfListingAndMegapixels", + new IndexQuery("Cost_Range:[Dx100 TO Dx300]"), + "facets/CameraFacets"); +`} + + + + +{`QCamera c = QCamera.camera; + +List facets = new ArrayList<>(); +Facet f1 = new Facet(); +f1.setName(c.manufacturer); +facets.add(f1); + +Facet f2 = new Facet(); +f2.setName(c.cost); +f2.setRanges(c.cost.lt(200), + c.cost.gt(200).and(c.cost.lt(400)), + c.cost.gt(400).and(c.cost.lt(600)), + c.cost.gt(600).and(c.cost.lt(800)), + c.cost.gt(800)); +facets.add(f2); + +Facet f3 = new Facet(); +f3.setName(c.megapixels); +f3.setRanges(c.megapixels.lt(3), + c.megapixels.gt(3).and(c.megapixels.lt(7)), + c.megapixels.gt(7).and(c.megapixels.lt(10)), + c.megapixels.gt(10)); +facets.add(f3); +`} + + + + +### Stale results + +The faceted search does not take into account a staleness of an index. You can't wait for non stale results by customizing your query with one of `waitForNonStaleResultsXXX` method. + + diff --git a/versioned_docs/version-3.5/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_filtering-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_handling-document-relationships-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_handling-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_handling-document-relationships-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_handling-document-relationships-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_handling-document-relationships-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_handling-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_handling-document-relationships-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_handling-document-relationships-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_highlights-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_highlights-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_highlights-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_highlights-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_highlights-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_highlights-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_highlights-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_highlights-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_intersection-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_paging-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_paging-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_paging-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_paging-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_paging-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_paging-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_paging-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_projections-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_projections-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_searching-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_searching-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_sorting-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_spatial-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_spatial-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_spatial-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_spatial-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-3.5/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-3.5/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-3.5/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-3.5/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-3.5/indexes/querying/dynamic-aggregation.mdx b/versioned_docs/version-3.5/indexes/querying/dynamic-aggregation.mdx index 7daf0c8130..ef3234d8df 100644 --- a/versioned_docs/version-3.5/indexes/querying/dynamic-aggregation.mdx +++ b/versioned_docs/version-3.5/indexes/querying/dynamic-aggregation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DynamicAggregationCsharp from './_dynamic-aggregation-csharp.mdx'; -import DynamicAggregationJava from './_dynamic-aggregation-java.mdx'; +import DynamicAggregationCsharp from './content/_dynamic-aggregation-csharp.mdx'; +import DynamicAggregationJava from './content/_dynamic-aggregation-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/faceted-search.mdx b/versioned_docs/version-3.5/indexes/querying/faceted-search.mdx index 6e917cb1ea..db769634cd 100644 --- a/versioned_docs/version-3.5/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-3.5/indexes/querying/faceted-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/filtering.mdx b/versioned_docs/version-3.5/indexes/querying/filtering.mdx index f95e602be8..f5ad6033bf 100644 --- a/versioned_docs/version-3.5/indexes/querying/filtering.mdx +++ b/versioned_docs/version-3.5/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/handling-document-relationships.mdx b/versioned_docs/version-3.5/indexes/querying/handling-document-relationships.mdx index 196dd9ec93..d90ac2d3fa 100644 --- a/versioned_docs/version-3.5/indexes/querying/handling-document-relationships.mdx +++ b/versioned_docs/version-3.5/indexes/querying/handling-document-relationships.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandlingDocumentRelationshipsCsharp from './_handling-document-relationships-csharp.mdx'; -import HandlingDocumentRelationshipsJava from './_handling-document-relationships-java.mdx'; +import HandlingDocumentRelationshipsCsharp from './content/_handling-document-relationships-csharp.mdx'; +import HandlingDocumentRelationshipsJava from './content/_handling-document-relationships-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/highlights.mdx b/versioned_docs/version-3.5/indexes/querying/highlights.mdx index b3d4f4c276..9bbaea6e2d 100644 --- a/versioned_docs/version-3.5/indexes/querying/highlights.mdx +++ b/versioned_docs/version-3.5/indexes/querying/highlights.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightsCsharp from './_highlights-csharp.mdx'; -import HighlightsJava from './_highlights-java.mdx'; +import HighlightsCsharp from './content/_highlights-csharp.mdx'; +import HighlightsJava from './content/_highlights-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/intersection.mdx b/versioned_docs/version-3.5/indexes/querying/intersection.mdx index 0d06d9311a..742ca9b295 100644 --- a/versioned_docs/version-3.5/indexes/querying/intersection.mdx +++ b/versioned_docs/version-3.5/indexes/querying/intersection.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/paging.mdx b/versioned_docs/version-3.5/indexes/querying/paging.mdx index 87bdf3226d..e813030ad5 100644 --- a/versioned_docs/version-3.5/indexes/querying/paging.mdx +++ b/versioned_docs/version-3.5/indexes/querying/paging.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/projections.mdx b/versioned_docs/version-3.5/indexes/querying/projections.mdx index 1c2d7ed365..f01c2dd0d5 100644 --- a/versioned_docs/version-3.5/indexes/querying/projections.mdx +++ b/versioned_docs/version-3.5/indexes/querying/projections.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-3.5/indexes/querying/query-vs-document-query.mdx index ffc799c354..8bb7c5e751 100644 --- a/versioned_docs/version-3.5/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-3.5/indexes/querying/query-vs-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/searching.mdx b/versioned_docs/version-3.5/indexes/querying/searching.mdx index 3f38918857..5918d72a38 100644 --- a/versioned_docs/version-3.5/indexes/querying/searching.mdx +++ b/versioned_docs/version-3.5/indexes/querying/searching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/sorting.mdx b/versioned_docs/version-3.5/indexes/querying/sorting.mdx index 9ad7e60838..8172ba7af0 100644 --- a/versioned_docs/version-3.5/indexes/querying/sorting.mdx +++ b/versioned_docs/version-3.5/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/spatial.mdx b/versioned_docs/version-3.5/indexes/querying/spatial.mdx index 40ee49a4ed..81fe740983 100644 --- a/versioned_docs/version-3.5/indexes/querying/spatial.mdx +++ b/versioned_docs/version-3.5/indexes/querying/spatial.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-3.5/indexes/querying/suggestions.mdx b/versioned_docs/version-3.5/indexes/querying/suggestions.mdx index 698c8a7591..391158b55a 100644 --- a/versioned_docs/version-3.5/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-3.5/indexes/querying/suggestions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; diff --git a/versioned_docs/version-3.5/start/_getting-started-csharp.mdx b/versioned_docs/version-3.5/start/content/_getting-started-csharp.mdx similarity index 100% rename from versioned_docs/version-3.5/start/_getting-started-csharp.mdx rename to versioned_docs/version-3.5/start/content/_getting-started-csharp.mdx diff --git a/versioned_docs/version-3.5/start/_getting-started-java.mdx b/versioned_docs/version-3.5/start/content/_getting-started-java.mdx similarity index 100% rename from versioned_docs/version-3.5/start/_getting-started-java.mdx rename to versioned_docs/version-3.5/start/content/_getting-started-java.mdx diff --git a/versioned_docs/version-3.5/start/getting-started.mdx b/versioned_docs/version-3.5/start/getting-started.mdx index 1bb9f31ea4..80e5cdab14 100644 --- a/versioned_docs/version-3.5/start/getting-started.mdx +++ b/versioned_docs/version-3.5/start/getting-started.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GettingStartedCsharp from './_getting-started-csharp.mdx'; -import GettingStartedJava from './_getting-started-java.mdx'; +import GettingStartedCsharp from './content/_getting-started-csharp.mdx'; +import GettingStartedJava from './content/_getting-started-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-4.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-4.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 2da0998998..7a7756c6fa 100644 --- a/versioned_docs/version-4.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-4.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-4.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-4.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-4.0/client-api/changes/what-is-changes-api.mdx index 8427c7ec71..8379a82942 100644 --- a/versioned_docs/version-4.0/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-4.0/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-4.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-4.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-4.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-4.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-4.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-4.0/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-4.0/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-4.0/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-4.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 5067204d77..d6621b1518 100644 --- a/versioned_docs/version-4.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-4.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-4.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-4.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-4.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-4.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-4.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 8a572be20e..b41fede16b 100644 --- a/versioned_docs/version-4.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-4.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-4.0/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/delete.mdx b/versioned_docs/version-4.0/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-4.0/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-4.0/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/commands/documents/get.mdx b/versioned_docs/version-4.0/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-4.0/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-4.0/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-4.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-4.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-4.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-4.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-4.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-4.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-4.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/commands/documents/put.mdx b/versioned_docs/version-4.0/client-api/commands/documents/put.mdx index 1178a97257..016c1f2cb7 100644 --- a/versioned_docs/version-4.0/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-4.0/client-api/commands/documents/put.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_conventions-java.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_conventions-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_conventions-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_conventions-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-java.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-nodejs.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_load-balance-and-failover-nodejs.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_querying-java.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_querying-nodejs.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_querying-nodejs.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-4.0/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/conventions.mdx b/versioned_docs/version-4.0/client-api/configuration/conventions.mdx index f68ae0f3cd..9f1e23100f 100644 --- a/versioned_docs/version-4.0/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/conventions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsJava from './_conventions-java.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsJava from './content/_conventions-java.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-4.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-4.0/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/load-balance-and-failover.mdx b/versioned_docs/version-4.0/client-api/configuration/load-balance-and-failover.mdx index 6fcd694545..190894c2ec 100644 --- a/versioned_docs/version-4.0/client-api/configuration/load-balance-and-failover.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/load-balance-and-failover.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceAndFailoverCsharp from './_load-balance-and-failover-csharp.mdx'; -import LoadBalanceAndFailoverJava from './_load-balance-and-failover-java.mdx'; -import LoadBalanceAndFailoverNodejs from './_load-balance-and-failover-nodejs.mdx'; +import LoadBalanceAndFailoverCsharp from './content/_load-balance-and-failover-csharp.mdx'; +import LoadBalanceAndFailoverJava from './content/_load-balance-and-failover-java.mdx'; +import LoadBalanceAndFailoverNodejs from './content/_load-balance-and-failover-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/querying.mdx b/versioned_docs/version-4.0/client-api/configuration/querying.mdx index c5841d1074..b00addcfda 100644 --- a/versioned_docs/version-4.0/client-api/configuration/querying.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/querying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/configuration/serialization.mdx b/versioned_docs/version-4.0/client-api/configuration/serialization.mdx index 7b97467d9e..f531b1b2d0 100644 --- a/versioned_docs/version-4.0/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-4.0/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-4.0/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-4.0/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/_creating-document-store-java.mdx b/versioned_docs/version-4.0/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-4.0/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-4.0/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-4.0/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-4.0/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-4.0/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-4.0/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-4.0/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-4.0/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-4.0/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-4.0/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-4.0/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/creating-document-store.mdx b/versioned_docs/version-4.0/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-4.0/client-api/creating-document-store.mdx +++ b/versioned_docs/version-4.0/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index bcc8c85ea4..483a687210 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index 792bcc72fa..19577eff6d 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/api-overview.mdx index 2d4cfeb063..3d4ef0ed43 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/examples.mdx index 8fd4abb96a..54b3f59e5d 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 00e96e6291..09a0baf74b 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/api-overview.mdx index d4855b543e..8031f37d02 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-4.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/examples.mdx index 5e2016a517..bc5bcbe901 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-4.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-4.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-4.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-java.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-java.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-java.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-java.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-java.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-java.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-nodejs.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/document-identifiers/_working-with-document-identifiers-nodejs.mdx rename to versioned_docs/version-4.0/client-api/document-identifiers/content/_working-with-document-identifiers-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/hilo-algorithm.mdx index 0ce06ebcfa..e0474c9454 100644 --- a/versioned_docs/version-4.0/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-4.0/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; -import HiloAlgorithmJava from './_hilo-algorithm-java.mdx'; -import HiloAlgorithmNodejs from './_hilo-algorithm-nodejs.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmJava from './content/_hilo-algorithm-java.mdx'; +import HiloAlgorithmNodejs from './content/_hilo-algorithm-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-4.0/client-api/document-identifiers/working-with-document-identifiers.mdx index 8b3dfc0b15..b81b004af2 100644 --- a/versioned_docs/version-4.0/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-4.0/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; -import WorkingWithDocumentIdentifiersJava from './_working-with-document-identifiers-java.mdx'; -import WorkingWithDocumentIdentifiersNodejs from './_working-with-document-identifiers-nodejs.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersJava from './content/_working-with-document-identifiers-java.mdx'; +import WorkingWithDocumentIdentifiersNodejs from './content/_working-with-document-identifiers-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-4.0/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-4.0/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-4.0/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-4.0/client-api/how-to/handle-document-relationships.mdx index 9c633ad5a9..b20ad2dcab 100644 --- a/versioned_docs/version-4.0/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-4.0/client-api/how-to/handle-document-relationships.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-4.0/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-4.0/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-4.0/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-4.0/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-4.0/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-4.0/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/net-client-versions.mdx b/versioned_docs/version-4.0/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-4.0/client-api/net-client-versions.mdx +++ b/versioned_docs/version-4.0/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-4.0/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-4.0/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-4.0/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-4.0/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-4.0/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-4.0/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-4.0/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-4.0/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-4.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-4.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-4.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 44907a01a9..8b9780aee1 100644 --- a/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index a7d32b6528..27f60b056c 100644 --- a/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-4.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/overview.mdx index 06412b791f..bd1ec58ac8 100644 --- a/versioned_docs/version-4.0/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-4.0/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-4.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-4.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-4.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/_delete-by-query-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/_delete-by-query-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/_delete-by-query-java.mdx b/versioned_docs/version-4.0/client-api/operations/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/_delete-by-query-java.mdx rename to versioned_docs/version-4.0/client-api/operations/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-4.0/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-4.0/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/delete-by-query.mdx b/versioned_docs/version-4.0/client-api/operations/delete-by-query.mdx index fa8a8b681d..50bc2515e9 100644 --- a/versioned_docs/version-4.0/client-api/operations/delete-by-query.mdx +++ b/versioned_docs/version-4.0/client-api/operations/delete-by-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-4.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-4.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-4.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 8b3e793df4..d066d2eb37 100644 --- a/versioned_docs/version-4.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-4.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 960030cb78..f3bc0e847d 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx index fd66f74e2b..1be313d638 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/_get-collection-statistics-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/_get-collection-statistics-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/_get-statistics-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/_get-statistics-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-statistics-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/_get-statistics-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/_get-statistics-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/content/_get-statistics-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/add-etl.mdx index e699942ebc..efc559a2c9 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/reset-etl.mdx index 5302266877..931ba3b21f 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/update-etl.mdx index 9c22d4cb52..5b9b1a4c96 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/get-collection-statistics.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/get-collection-statistics.mdx index ac33eb1e8a..aa9d87c7ce 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/get-collection-statistics.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/get-collection-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCollectionStatisticsCsharp from './_get-collection-statistics-csharp.mdx'; -import GetCollectionStatisticsJava from './_get-collection-statistics-java.mdx'; +import GetCollectionStatisticsCsharp from './content/_get-collection-statistics-csharp.mdx'; +import GetCollectionStatisticsJava from './content/_get-collection-statistics-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/get-statistics.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/get-statistics.mdx index 7ab59532a6..281d3a0a84 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/get-statistics.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/get-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatisticsCsharp from './_get-statistics-csharp.mdx'; -import GetStatisticsJava from './_get-statistics-java.mdx'; +import GetStatisticsCsharp from './content/_get-statistics-csharp.mdx'; +import GetStatisticsJava from './content/_get-statistics-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/identities/get-identities.mdx index 3815c90caf..6d6de5138a 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-4.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/delete-index.mdx index b7de8fa9ea..d31358936f 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/disable-index.mdx index 0c5806cf4d..6c084fd5d4 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/enable-index.mdx index 6506876348..4a238c903e 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-errors.mdx index 677b5cff6c..1f167fa168 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-names.mdx index b2335e394f..b5ae1f846f 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index.mdx index a3c77a8ac9..2a43d3f84c 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-indexes.mdx index e6179f273c..2b73a09b0d 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-terms.mdx index 1bf8971406..e76ea582dd 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/index-has-changed.mdx index 1662b2d172..7f88cbc329 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/put-indexes.mdx index 742060167b..aec419ba4e 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/reset-index.mdx index 6171b19111..034cae96a8 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-lock.mdx index a38fcd9e29..de6e64089e 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-priority.mdx index c186cbbb2a..eaf94b9e7b 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-index.mdx index 6f9fd53715..e5de41e7ca 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-indexing.mdx index 01a0c2a0e5..12c1cadfc5 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-index.mdx index bc0a9a5470..b672d7c320 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-indexing.mdx index f0d62c3000..d8186af3a8 100644 --- a/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-4.0/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-4.0/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-4.0/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-4.0/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-4.0/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/patching/set-based.mdx b/versioned_docs/version-4.0/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-4.0/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-4.0/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/patching/single-document.mdx b/versioned_docs/version-4.0/client-api/operations/patching/single-document.mdx index 096bfb338a..f9984f85f9 100644 --- a/versioned_docs/version-4.0/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-4.0/client-api/operations/patching/single-document.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/add-database-node.mdx index 2cb4d31d60..b9fe604e59 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/add-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx index 3e477c4628..3604a1bf15 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/delete-certificate.mdx index c5ee5cdb94..b48dc894cc 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificate.mdx index 1270f2258f..1ea0ec1977 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificates.mdx index 65bb2ee0e5..f4a73f4a61 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx index fd51c3387b..7e74e2db59 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/compact-database.mdx index ed8832538e..696f5a0b6c 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/compact-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseJava from './_compact-database-java.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseJava from './content/_compact-database-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index c1c0ac0a7d..ac6e75d815 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 9e3504cf11..7cfc9f4934 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_compact-database-java.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_compact-database-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_compact-database-java.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_compact-database-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/create-database.mdx index abd4d68c0d..ea75a81467 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-4.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/promote-database-node.mdx index a1b342c55a..14e10ef548 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/restore-backup.mdx index 36adcb65d2..817791da95 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/restore-backup.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-4.0/client-api/operations/server-wide/toggle-databases-state.mdx index 61b9d9a396..fd4c1e4e85 100644 --- a/versioned_docs/version-4.0/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-4.0/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/operations/what-are-operations.mdx b/versioned_docs/version-4.0/client-api/operations/what-are-operations.mdx index 7c2ad27db8..9f02c7218e 100644 --- a/versioned_docs/version-4.0/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-4.0/client-api/operations/what-are-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_deleting-csharp.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_deleting-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_deleting-java.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_deleting-java.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_deleting-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_loading-csharp.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_loading-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_loading-java.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_loading-java.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_loading-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_loading-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_storing-csharp.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_storing-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_storing-java.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_storing-java.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_storing-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_storing-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/attachments/deleting.mdx b/versioned_docs/version-4.0/client-api/session/attachments/deleting.mdx index 3433931530..9470a16e40 100644 --- a/versioned_docs/version-4.0/client-api/session/attachments/deleting.mdx +++ b/versioned_docs/version-4.0/client-api/session/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/attachments/loading.mdx b/versioned_docs/version-4.0/client-api/session/attachments/loading.mdx index f4383876b8..b2e85ff1b8 100644 --- a/versioned_docs/version-4.0/client-api/session/attachments/loading.mdx +++ b/versioned_docs/version-4.0/client-api/session/attachments/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/attachments/storing.mdx b/versioned_docs/version-4.0/client-api/session/attachments/storing.mdx index 2861d1ad25..47022f1708 100644 --- a/versioned_docs/version-4.0/client-api/session/attachments/storing.mdx +++ b/versioned_docs/version-4.0/client-api/session/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/attachments/what-are-attachments.mdx b/versioned_docs/version-4.0/client-api/session/attachments/what-are-attachments.mdx index f8d3bea98c..17b91b137b 100644 --- a/versioned_docs/version-4.0/client-api/session/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-4.0/client-api/session/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-4.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-4.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-4.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-4.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-4.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-4.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/deleting-entities.mdx b/versioned_docs/version-4.0/client-api/session/deleting-entities.mdx index 7830ac0cba..5d7364f947 100644 --- a/versioned_docs/version-4.0/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-4.0/client-api/session/how-to/check-if-document-exists.mdx index bbc783ee99..eedc8f6e13 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/check-if-document-exists.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-4.0/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-4.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-4.0/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-4.0/client-api/session/how-to/defer-operations.mdx index 4ee53ab9e4..b7f24d7163 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/defer-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-4.0/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-4.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-4.0/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-4.0/client-api/session/how-to/ignore-entity-changes.mdx index ec0fea1629..d46a577949 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-4.0/client-api/session/how-to/perform-operations-lazily.mdx index a58c0c1d16..1e12e4cd05 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyJava from './_perform-operations-lazily-java.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyJava from './content/_perform-operations-lazily-java.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-4.0/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-4.0/client-api/session/how-to/subscribe-to-events.mdx index 590fa0e3b9..fab422008b 100644 --- a/versioned_docs/version-4.0/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-4.0/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/loading-entities.mdx b/versioned_docs/version-4.0/client-api/session/loading-entities.mdx index 2a39a6fb00..8214ff7506 100644 --- a/versioned_docs/version-4.0/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/opening-a-session.mdx b/versioned_docs/version-4.0/client-api/session/opening-a-session.mdx index e10d20e091..78b5349381 100644 --- a/versioned_docs/version-4.0/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-4.0/client-api/session/opening-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-a-spatial-index-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-a-spatial-index-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-regex-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-use-search-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-use-search-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-4.0/client-api/session/querying/document-query/what-is-document-query.mdx index 3a9c042634..ab640dc7a4 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-customize-query.mdx index 2e9f4cd49b..d8110e41f3 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-get-query-statistics.mdx index 83a9c90774..433e7bbfad 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx index e715a770b3..1b6695fbca 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-queries-lazily.mdx index 542f959aed..14d0cc1782 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-project-query-results.mdx index 4064387648..9c7d07ff5c 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-query-a-spatial-index.mdx index 05614450e3..3dcaa7c341 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; -import HowToQueryASpatialIndexNodejs from './_how-to-query-a-spatial-index-nodejs.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexNodejs from './content/_how-to-query-a-spatial-index-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-query-with-exact-match.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-query-with-exact-match.mdx index 29dadbe6eb..c6befd9e24 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-query-with-exact-match.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-query-with-exact-match.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryWithExactMatchCsharp from './_how-to-query-with-exact-match-csharp.mdx'; -import HowToQueryWithExactMatchJava from './_how-to-query-with-exact-match-java.mdx'; -import HowToQueryWithExactMatchNodejs from './_how-to-query-with-exact-match-nodejs.mdx'; +import HowToQueryWithExactMatchCsharp from './content/_how-to-query-with-exact-match-csharp.mdx'; +import HowToQueryWithExactMatchJava from './content/_how-to-query-with-exact-match-java.mdx'; +import HowToQueryWithExactMatchNodejs from './content/_how-to-query-with-exact-match-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-query.mdx index e62fb53f99..73070cca5b 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryJava from './_how-to-query-java.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryJava from './content/_how-to-query-java.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-stream-query-results.mdx index 75d86a60b2..69bde8d43d 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-regex.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-regex.mdx index d46f82cab1..e0e9f41896 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-regex.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseRegexCsharp from './_how-to-use-regex-csharp.mdx'; -import HowToUseRegexJava from './_how-to-use-regex-java.mdx'; -import HowToUseRegexNodejs from './_how-to-use-regex-nodejs.mdx'; +import HowToUseRegexCsharp from './content/_how-to-use-regex-csharp.mdx'; +import HowToUseRegexJava from './content/_how-to-use-regex-java.mdx'; +import HowToUseRegexNodejs from './content/_how-to-use-regex-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-search.mdx index c58780ba8c..bb2e84794d 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-use-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; -import HowToUseSearchJava from './_how-to-use-search-java.mdx'; -import HowToUseSearchNodejs from './_how-to-use-search-nodejs.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; +import HowToUseSearchJava from './content/_how-to-use-search-java.mdx'; +import HowToUseSearchNodejs from './content/_how-to-use-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-4.0/client-api/session/querying/how-to-work-with-suggestions.mdx index 35155f00e2..b73a402884 100644 --- a/versioned_docs/version-4.0/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-4.0/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-4.0/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-4.0/client-api/session/revisions/loading.mdx b/versioned_docs/version-4.0/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-4.0/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-4.0/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-4.0/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-4.0/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-4.0/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/saving-changes.mdx b/versioned_docs/version-4.0/client-api/session/saving-changes.mdx index a8d9f9cc82..386e7a25c8 100644 --- a/versioned_docs/version-4.0/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-4.0/client-api/session/saving-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/storing-entities.mdx b/versioned_docs/version-4.0/client-api/session/storing-entities.mdx index 09787c1800..dafb1abe29 100644 --- a/versioned_docs/version-4.0/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/updating-entities.mdx b/versioned_docs/version-4.0/client-api/session/updating-entities.mdx index c7a719d596..58a56a1004 100644 --- a/versioned_docs/version-4.0/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-4.0/client-api/session/updating-entities.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-4.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx index 353c8216a1..7939b1ea8e 100644 --- a/versioned_docs/version-4.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-4.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-4.0/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-4.0/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-4.0/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/setting-up-default-database.mdx b/versioned_docs/version-4.0/client-api/setting-up-default-database.mdx index 75fc4c2450..b217f301b3 100644 --- a/versioned_docs/version-4.0/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-4.0/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-4.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-4.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-4.0/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-4.0/client-api/smuggler/what-is-smuggler.mdx index f1af37fb68..da1d8be3d1 100644 --- a/versioned_docs/version-4.0/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-4.0/client-api/smuggler/what-is-smuggler.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; diff --git a/versioned_docs/version-4.0/client-api/what-is-a-document-store.mdx b/versioned_docs/version-4.0/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-4.0/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-4.0/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-4.0/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-4.0/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-4.0/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_index-query-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_index-query-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_query-result-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_query-result-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/_stream-result-csharp.mdx b/versioned_docs/version-4.0/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-4.0/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-4.0/glossary/delete-command-data.mdx b/versioned_docs/version-4.0/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-4.0/glossary/delete-command-data.mdx +++ b/versioned_docs/version-4.0/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/index-query.mdx b/versioned_docs/version-4.0/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-4.0/glossary/index-query.mdx +++ b/versioned_docs/version-4.0/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/patch-command-data.mdx b/versioned_docs/version-4.0/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-4.0/glossary/patch-command-data.mdx +++ b/versioned_docs/version-4.0/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/put-command-data.mdx b/versioned_docs/version-4.0/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-4.0/glossary/put-command-data.mdx +++ b/versioned_docs/version-4.0/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/query-result.mdx b/versioned_docs/version-4.0/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-4.0/glossary/query-result.mdx +++ b/versioned_docs/version-4.0/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/stream-query-statistics.mdx b/versioned_docs/version-4.0/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-4.0/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-4.0/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-4.0/glossary/stream-result.mdx b/versioned_docs/version-4.0/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-4.0/glossary/stream-result.mdx +++ b/versioned_docs/version-4.0/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-4.0/indexes/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/_fanout-indexes-csharp.mdx deleted file mode 100644 index 8e554238ad..0000000000 --- a/versioned_docs/version-4.0/indexes/_fanout-indexes-csharp.mdx +++ /dev/null @@ -1,100 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - -{`public class Orders_ByProduct : AbstractIndexCreationTask -\{ - public Orders_ByProduct() - \{ - Map = orders => from order in orders - from orderLine in order.Lines - select new - \{ - orderLine.Product, - orderLine.ProductName - \}; - \} -\} -`} - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - -{`public class Product_Sales : AbstractIndexCreationTask -\{ - public class Result - \{ - public string Product \{ get; set; \} - public int Count \{ get; set; \} - public decimal Total; - \} - - public Product_Sales() - \{ - Map = orders => from order in orders - from line in order.Lines - select new Result - \{ - Product = line.Product, - Count = 1, - Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) - \}; - - Reduce = results => from result in results - group result by result.Product - into g - select new - \{ - Product = g.Key, - Count = g.Sum(x => x.Count), - Total = g.Sum(x => x.Total) - \}; - \} -\} -`} - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.0/indexes/_fanout-indexes-java.mdx b/versioned_docs/version-4.0/indexes/_fanout-indexes-java.mdx deleted file mode 100644 index 8c2b34d09f..0000000000 --- a/versioned_docs/version-4.0/indexes/_fanout-indexes-java.mdx +++ /dev/null @@ -1,79 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask \{ - public Orders_ByProduct() \{ - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new \{ " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "\})"; - \} -\} -`} - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - -{`public static class Product_Sales extends AbstractIndexCreationTask \{ - public Product_Sales() \{ - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new \{ " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "\})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new \{\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "\})"; - \} -\} -`} - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index 708909e608..0000000000 --- a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -\{ - public Animals_ByName() - \{ - AddMap(cats => from c in cats select new \{ c.Name \}); - - AddMap(dogs => from d in dogs select new \{ d.Name \}); - \} -\} -`} - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 286dd46a19..0000000000 --- a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new \{ name = c.name\})"); -maps.add("docs.Dogs.Select(c => new \{ name = c.name\})"); -indexDefinition.setMaps(maps); -`} - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 3f0bb8f19e..0000000000 --- a/versioned_docs/version-4.0/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - -{`const indexDefinition = new IndexDefinition(); -indexDefinition.name = "Animals/ByName"; -indexDefinition.maps = new Set([ - "docs.Cats.Select(c => new \{ name = c.name\})", - "docs.Dogs.Select(c => new \{ name = c.name\})" -]); -`} - - - -And query it like this: - - - - -{`const results = await session - .query({ indexName: "Animals/ByName" }) - .whereEquals("name", "Mitzy") - .all(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{` -\{ - const store = new DocumentStore(); - store.conventions.findCollectionName = clazz => \{ - if (clazz instanceof Animal) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}; -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.0/indexes/boosting.mdx b/versioned_docs/version-4.0/indexes/boosting.mdx index 63937b73b3..4e299192ad 100644 --- a/versioned_docs/version-4.0/indexes/boosting.mdx +++ b/versioned_docs/version-4.0/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/_boosting-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_boosting-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_boosting-java.mdx b/versioned_docs/version-4.0/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_boosting-java.mdx rename to versioned_docs/version-4.0/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_boosting-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-4.0/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-4.0/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_extending-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/content/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-csharp.mdx new file mode 100644 index 0000000000..f18c4e0c91 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-csharp.mdx @@ -0,0 +1,100 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + +{`public class Orders_ByProduct : AbstractIndexCreationTask +\{ + public Orders_ByProduct() + \{ + Map = orders => from order in orders + from orderLine in order.Lines + select new + \{ + orderLine.Product, + orderLine.ProductName + \}; + \} +\} +`} + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + +{`public class Product_Sales : AbstractIndexCreationTask +\{ + public class Result + \{ + public string Product \{ get; set; \} + public int Count \{ get; set; \} + public decimal Total; + \} + + public Product_Sales() + \{ + Map = orders => from order in orders + from line in order.Lines + select new Result + \{ + Product = line.Product, + Count = 1, + Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) + \}; + + Reduce = results => from result in results + group result by result.Product + into g + select new + \{ + Product = g.Key, + Count = g.Sum(x => x.Count), + Total = g.Sum(x => x.Total) + \}; + \} +\} +`} + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.0/indexes/content/_fanout-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-java.mdx new file mode 100644 index 0000000000..838e2ae5f9 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-java.mdx @@ -0,0 +1,79 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask \{ + public Orders_ByProduct() \{ + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new \{ " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "\})"; + \} +\} +`} + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + +{`public static class Product_Sales extends AbstractIndexCreationTask \{ + public Product_Sales() \{ + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new \{ " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "\})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new \{\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "\})"; + \} +\} +`} + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.0/indexes/_fanout-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-nodejs.mdx similarity index 94% rename from versioned_docs/version-4.0/indexes/_fanout-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_fanout-indexes-nodejs.mdx index da0ba60d99..2d81085d1a 100644 --- a/versioned_docs/version-4.0/indexes/_fanout-indexes-nodejs.mdx +++ b/versioned_docs/version-4.0/indexes/content/_fanout-indexes-nodejs.mdx @@ -68,11 +68,11 @@ RavenDB will give you a performance hint regarding high fanout ratio using the S Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) The details will give you the following info: -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). diff --git a/versioned_docs/version-4.0/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-basics-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-hierarchical-data-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..7b2af3161b --- /dev/null +++ b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +\{ + public Animals_ByName() + \{ + AddMap(cats => from c in cats select new \{ c.Name \}); + + AddMap(dogs => from d in dogs select new \{ d.Name \}); + \} +\} +`} + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..d78126f9b2 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new \{ name = c.name\})"); +maps.add("docs.Dogs.Select(c => new \{ name = c.name\})"); +indexDefinition.setMaps(maps); +`} + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..8906275cfa --- /dev/null +++ b/versioned_docs/version-4.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + +{`const indexDefinition = new IndexDefinition(); +indexDefinition.name = "Animals/ByName"; +indexDefinition.maps = new Set([ + "docs.Cats.Select(c => new \{ name = c.name\})", + "docs.Dogs.Select(c => new \{ name = c.name\})" +]); +`} + + + +And query it like this: + + + + +{`const results = await session + .query({ indexName: "Animals/ByName" }) + .whereEquals("name", "Mitzy") + .all(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{` +\{ + const store = new DocumentStore(); + store.conventions.findCollectionName = clazz => \{ + if (clazz instanceof Animal) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}; +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.0/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-related-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-related-documents-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-related-documents-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-related-documents-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-related-documents-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-related-documents-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-4.0/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-4.0/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_sorting-and-collation-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_sorting-and-collation-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_sorting-and-collation-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_sorting-and-collation-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_stale-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-4.0/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-4.0/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-analyzers-java.mdx b/versioned_docs/version-4.0/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-4.0/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-dynamic-fields-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-dynamic-fields-java.mdx rename to versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-dynamic-fields-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_using-dynamic-fields-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-4.0/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-4.0/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-4.0/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-4.0/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-4.0/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-4.0/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-4.0/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-4.0/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-4.0/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-4.0/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-4.0/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-4.0/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/creating-and-deploying.mdx b/versioned_docs/version-4.0/indexes/creating-and-deploying.mdx index 7207cc5780..e01dfd772e 100644 --- a/versioned_docs/version-4.0/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-4.0/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/extending-indexes.mdx b/versioned_docs/version-4.0/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-4.0/indexes/extending-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/fanout-indexes.mdx b/versioned_docs/version-4.0/indexes/fanout-indexes.mdx index 8b92e7b84d..aa04c94321 100644 --- a/versioned_docs/version-4.0/indexes/fanout-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/fanout-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FanoutIndexesCsharp from './_fanout-indexes-csharp.mdx'; -import FanoutIndexesJava from './_fanout-indexes-java.mdx'; -import FanoutIndexesNodejs from './_fanout-indexes-nodejs.mdx'; +import FanoutIndexesCsharp from './content/_fanout-indexes-csharp.mdx'; +import FanoutIndexesJava from './content/_fanout-indexes-java.mdx'; +import FanoutIndexesNodejs from './content/_fanout-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-basics.mdx b/versioned_docs/version-4.0/indexes/indexing-basics.mdx index 72b153a25f..15560b37fc 100644 --- a/versioned_docs/version-4.0/indexes/indexing-basics.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-4.0/indexes/indexing-hierarchical-data.mdx index fa332d040c..e40eb076fc 100644 --- a/versioned_docs/version-4.0/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-hierarchical-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-4.0/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-4.0/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-4.0/indexes/indexing-polymorphic-data.mdx index 1398672654..510d0e7762 100644 --- a/versioned_docs/version-4.0/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-polymorphic-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-related-documents.mdx b/versioned_docs/version-4.0/indexes/indexing-related-documents.mdx index 8d88aa18eb..0f5cdebf2e 100644 --- a/versioned_docs/version-4.0/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-related-documents.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/indexing-spatial-data.mdx b/versioned_docs/version-4.0/indexes/indexing-spatial-data.mdx index 74afb24462..f451857e4d 100644 --- a/versioned_docs/version-4.0/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-4.0/indexes/indexing-spatial-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/map-indexes.mdx b/versioned_docs/version-4.0/indexes/map-indexes.mdx index a9a5371458..3857e1c0e3 100644 --- a/versioned_docs/version-4.0/indexes/map-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/map-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/map-reduce-indexes.mdx b/versioned_docs/version-4.0/indexes/map-reduce-indexes.mdx index 6596e14a76..99d55d99a7 100644 --- a/versioned_docs/version-4.0/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/map-reduce-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/multi-map-indexes.mdx b/versioned_docs/version-4.0/indexes/multi-map-indexes.mdx index 02fad018c5..bb7bc5c658 100644 --- a/versioned_docs/version-4.0/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/multi-map-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 01b66b3e5d..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,349 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **Cost** field, return the count of the following ranges: - - * Cost < 200.0 - * 200.0 <= Cost < 400.0 - * 400.0 <= Cost < 600.0 - * 600.0 <= Cost < 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels < 7.0 - * 7.0 <= Megapixels < 10.0 - * Megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "Manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "Cost", - "Values": [ - \{ - "Count": 6, - "Range": "Cost <= 200" - \}, - \{ - "Count": 2, - "Range": "Cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "Cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "Cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "Cost >= 800" - \} - ] - \}, - \{ - "Name": "Megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "Megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "Megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "Megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "Megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.0/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-4.0/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 54c908d478..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.0/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 690e4df1df..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,312 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`export class Camera \{ - constructor(manufacturer, model, \{ - dateOfListing, - cost, - zoom, - megapixels, - imageStabilizer - \}) \{ - this.manufacturer = manufacturer; - this.model = model; - this.dateOfListing = dateOfListing; - this.cost = cost; - this.zoom = zoom; - this.megapixels = megapixels; - this.imageStabilizer = imageStabilizer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = \`from camera in docs.Cameras select new \{ - camera.manufacturer, - camera.model, - camera.cost, - camera.dateOfListing, - camera.megapixels - \}\`; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`const facetSetup = new FacetSetup(); -facetSetup.facets = facets; -facetSetup.rangeFacets = rangeFacets; - -await session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.0/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ecb4312302..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.0/indexes/querying/_paging-java.mdx b/versioned_docs/version-4.0/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-4.0/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index e52c0cff7a..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a Fanout index. - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.0/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/_spatial-csharp.mdx deleted file mode 100644 index b8e29cae09..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_spatial-csharp.mdx +++ /dev/null @@ -1,165 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `RelatesToShape` - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .Query() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`public class Events_ByCoordinates : AbstractIndexCreationTask -{ - public Events_ByCoordinates() - { - Map = events => from e in events - select new - { - Coordinates = CreateSpatialField(e.Latitude, e.Longitude) - }; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(Coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.0/indexes/querying/_spatial-java.mdx b/versioned_docs/version-4.0/indexes/querying/_spatial-java.mdx deleted file mode 100644 index 052325a8dc..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.0/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/_spatial-nodejs.mdx deleted file mode 100644 index 77542032c5..0000000000 --- a/versioned_docs/version-4.0/indexes/querying/_spatial-nodejs.mdx +++ /dev/null @@ -1,122 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape()` - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - "Within" - )) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`const results = await session - .query({ indexName: "Events/ByCoordinates" }) - .spatial("coordinates", - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`class Events_ByCoordinates extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Events.Select(e => new { - Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) - })\`; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.0/indexes/querying/basics.mdx b/versioned_docs/version-4.0/indexes/querying/basics.mdx index f1cbf38302..23f7507680 100644 --- a/versioned_docs/version-4.0/indexes/querying/basics.mdx +++ b/versioned_docs/version-4.0/indexes/querying/basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; -import BasicsNodejs from './_basics-nodejs.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; +import BasicsNodejs from './content/_basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/boosting.mdx b/versioned_docs/version-4.0/indexes/querying/boosting.mdx index 97dc2a028f..35a0a0b712 100644 --- a/versioned_docs/version-4.0/indexes/querying/boosting.mdx +++ b/versioned_docs/version-4.0/indexes/querying/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_basics-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_basics-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_basics-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_basics-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_basics-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_boosting-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_boosting-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_boosting-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_boosting-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_boosting-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_boosting-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_distinct-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..62e55bba88 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,349 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **Cost** field, return the count of the following ranges: + + * Cost < 200.0 + * 200.0 <= Cost < 400.0 + * 400.0 <= Cost < 600.0 + * 600.0 <= Cost < 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels < 7.0 + * 7.0 <= Megapixels < 10.0 + * Megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "Manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "Cost", + "Values": [ + \{ + "Count": 6, + "Range": "Cost <= 200" + \}, + \{ + "Count": 2, + "Range": "Cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "Cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "Cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "Cost >= 800" + \} + ] + \}, + \{ + "Name": "Megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "Megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "Megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "Megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "Megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..2dca93bfaf --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..2b4d199a3d --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,312 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`export class Camera \{ + constructor(manufacturer, model, \{ + dateOfListing, + cost, + zoom, + megapixels, + imageStabilizer + \}) \{ + this.manufacturer = manufacturer; + this.model = model; + this.dateOfListing = dateOfListing; + this.cost = cost; + this.zoom = zoom; + this.megapixels = megapixels; + this.imageStabilizer = imageStabilizer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = \`from camera in docs.Cameras select new \{ + camera.manufacturer, + camera.model, + camera.cost, + camera.dateOfListing, + camera.megapixels + \}\`; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`const facetSetup = new FacetSetup(); +facetSetup.facets = facets; +facetSetup.rangeFacets = rangeFacets; + +await session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.0/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_filtering-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_intersection-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..967fb68620 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2cc2e022a --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a Fanout index. + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.0/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_projections-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_projections-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_searching-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_searching-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_sorting-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/content/_spatial-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_spatial-csharp.mdx new file mode 100644 index 0000000000..1062993808 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_spatial-csharp.mdx @@ -0,0 +1,165 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `RelatesToShape` + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .Query() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`public class Events_ByCoordinates : AbstractIndexCreationTask +{ + public Events_ByCoordinates() + { + Map = events => from e in events + select new + { + Coordinates = CreateSpatialField(e.Latitude, e.Longitude) + }; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(Coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..9c11a03099 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.0/indexes/querying/content/_spatial-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_spatial-nodejs.mdx new file mode 100644 index 0000000000..9e318daef2 --- /dev/null +++ b/versioned_docs/version-4.0/indexes/querying/content/_spatial-nodejs.mdx @@ -0,0 +1,122 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape()` + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + "Within" + )) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`const results = await session + .query({ indexName: "Events/ByCoordinates" }) + .spatial("coordinates", + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`class Events_ByCoordinates extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Events.Select(e => new { + Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) + })\`; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.0/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-4.0/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-4.0/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-4.0/indexes/querying/content/_suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.0/indexes/querying/_suggestions-nodejs.mdx rename to versioned_docs/version-4.0/indexes/querying/content/_suggestions-nodejs.mdx diff --git a/versioned_docs/version-4.0/indexes/querying/distinct.mdx b/versioned_docs/version-4.0/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-4.0/indexes/querying/distinct.mdx +++ b/versioned_docs/version-4.0/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/faceted-search.mdx b/versioned_docs/version-4.0/indexes/querying/faceted-search.mdx index 642a2a77a5..b9e984e8b0 100644 --- a/versioned_docs/version-4.0/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-4.0/indexes/querying/faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/filtering.mdx b/versioned_docs/version-4.0/indexes/querying/filtering.mdx index e1b89ad3a5..4b63b98b17 100644 --- a/versioned_docs/version-4.0/indexes/querying/filtering.mdx +++ b/versioned_docs/version-4.0/indexes/querying/filtering.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/intersection.mdx b/versioned_docs/version-4.0/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-4.0/indexes/querying/intersection.mdx +++ b/versioned_docs/version-4.0/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/morelikethis.mdx b/versioned_docs/version-4.0/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-4.0/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-4.0/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/paging.mdx b/versioned_docs/version-4.0/indexes/querying/paging.mdx index 4a4f877127..1375a3d67e 100644 --- a/versioned_docs/version-4.0/indexes/querying/paging.mdx +++ b/versioned_docs/version-4.0/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/projections.mdx b/versioned_docs/version-4.0/indexes/querying/projections.mdx index f358bb4489..84724cf411 100644 --- a/versioned_docs/version-4.0/indexes/querying/projections.mdx +++ b/versioned_docs/version-4.0/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-4.0/indexes/querying/query-vs-document-query.mdx index b766203269..8d99869330 100644 --- a/versioned_docs/version-4.0/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-4.0/indexes/querying/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/searching.mdx b/versioned_docs/version-4.0/indexes/querying/searching.mdx index 0a795b76f4..e86b0e2e70 100644 --- a/versioned_docs/version-4.0/indexes/querying/searching.mdx +++ b/versioned_docs/version-4.0/indexes/querying/searching.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/sorting.mdx b/versioned_docs/version-4.0/indexes/querying/sorting.mdx index c52fe17092..b062bef563 100644 --- a/versioned_docs/version-4.0/indexes/querying/sorting.mdx +++ b/versioned_docs/version-4.0/indexes/querying/sorting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/spatial.mdx b/versioned_docs/version-4.0/indexes/querying/spatial.mdx index 1e4e0092b9..5df771eb7a 100644 --- a/versioned_docs/version-4.0/indexes/querying/spatial.mdx +++ b/versioned_docs/version-4.0/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/querying/suggestions.mdx b/versioned_docs/version-4.0/indexes/querying/suggestions.mdx index 8e46c2ed39..d5209e47da 100644 --- a/versioned_docs/version-4.0/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-4.0/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/sorting-and-collation.mdx b/versioned_docs/version-4.0/indexes/sorting-and-collation.mdx index 1155fa8a23..072ec4ff58 100644 --- a/versioned_docs/version-4.0/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-4.0/indexes/sorting-and-collation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; -import SortingAndCollationNodejs from './_sorting-and-collation-nodejs.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; +import SortingAndCollationNodejs from './content/_sorting-and-collation-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/stale-indexes.mdx b/versioned_docs/version-4.0/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-4.0/indexes/stale-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/storing-data-in-index.mdx b/versioned_docs/version-4.0/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-4.0/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-4.0/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/using-analyzers.mdx b/versioned_docs/version-4.0/indexes/using-analyzers.mdx index afe772cee0..4ee9fab1c6 100644 --- a/versioned_docs/version-4.0/indexes/using-analyzers.mdx +++ b/versioned_docs/version-4.0/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/using-dynamic-fields.mdx b/versioned_docs/version-4.0/indexes/using-dynamic-fields.mdx index c177368cf0..b9728119e7 100644 --- a/versioned_docs/version-4.0/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-4.0/indexes/using-dynamic-fields.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/using-term-vectors.mdx b/versioned_docs/version-4.0/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-4.0/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-4.0/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/indexes/what-are-indexes.mdx b/versioned_docs/version-4.0/indexes/what-are-indexes.mdx index baeb219b47..613babe12e 100644 --- a/versioned_docs/version-4.0/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-4.0/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.0/start/_test-driver-csharp.mdx b/versioned_docs/version-4.0/start/content/_test-driver-csharp.mdx similarity index 99% rename from versioned_docs/version-4.0/start/_test-driver-csharp.mdx rename to versioned_docs/version-4.0/start/content/_test-driver-csharp.mdx index 2f2b73d5b5..fd27e8f936 100644 --- a/versioned_docs/version-4.0/start/_test-driver-csharp.mdx +++ b/versioned_docs/version-4.0/start/content/_test-driver-csharp.mdx @@ -452,7 +452,7 @@ test-driver references that downloaded server, in your tests. 4. Queue/build away! #### Step 1 - Global Environment Variables for the build definition. -![VSTS Global Environment Variables](./assets/td1.png) +![VSTS Global Environment Variables](../assets/td1.png) #### Step 2 - Check/update your custom test-driver code @@ -473,7 +473,7 @@ if (!string.IsNullOrWhiteSpace(path)) #### Step 3 - Add a custom powershell task -![VSTS Add Custom Powershell Task](./assets/td2.png) +![VSTS Add Custom Powershell Task](../assets/td2.png) here's the code to quickly copy/paste the script into your VSTS task settings: diff --git a/versioned_docs/version-4.0/start/_test-driver-java.mdx b/versioned_docs/version-4.0/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-4.0/start/_test-driver-java.mdx rename to versioned_docs/version-4.0/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-4.0/start/test-driver.mdx b/versioned_docs/version-4.0/start/test-driver.mdx index 28b16a7c49..955583fe6e 100644 --- a/versioned_docs/version-4.0/start/test-driver.mdx +++ b/versioned_docs/version-4.0/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["java", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverJava from './_test-driver-java.mdx'; -import TestDriverCsharp from './_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-4.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-4.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-4.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-4.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-4.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-4.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 9b8b55bb6a..dccbc4d7f4 100644 --- a/versioned_docs/version-4.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-4.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-4.1/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-4.1/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-4.1/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-4.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-4.1/client-api/changes/what-is-changes-api.mdx index 111608118f..c761eaa47b 100644 --- a/versioned_docs/version-4.1/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-4.1/client-api/changes/what-is-changes-api.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-4.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-4.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-4.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-4.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-4.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-4.1/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-4.1/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-4.1/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-4.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 5067204d77..d6621b1518 100644 --- a/versioned_docs/version-4.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-4.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-4.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-4.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-4.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-4.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-4.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 8a572be20e..b41fede16b 100644 --- a/versioned_docs/version-4.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-4.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-4.1/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/delete.mdx b/versioned_docs/version-4.1/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-4.1/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-4.1/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/commands/documents/get.mdx b/versioned_docs/version-4.1/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-4.1/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-4.1/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-4.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-4.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-4.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-4.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-4.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-4.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-4.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/commands/documents/put.mdx b/versioned_docs/version-4.1/client-api/commands/documents/put.mdx index 1178a97257..016c1f2cb7 100644 --- a/versioned_docs/version-4.1/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-4.1/client-api/commands/documents/put.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_conventions-java.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_conventions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_conventions-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_conventions-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-java.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-nodejs.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_load-balance-and-failover-nodejs.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_querying-java.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-4.1/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/conventions.mdx b/versioned_docs/version-4.1/client-api/configuration/conventions.mdx index f68ae0f3cd..9f1e23100f 100644 --- a/versioned_docs/version-4.1/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/conventions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsJava from './_conventions-java.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsJava from './content/_conventions-java.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-4.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-4.1/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/load-balance-and-failover.mdx b/versioned_docs/version-4.1/client-api/configuration/load-balance-and-failover.mdx index 6fcd694545..190894c2ec 100644 --- a/versioned_docs/version-4.1/client-api/configuration/load-balance-and-failover.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/load-balance-and-failover.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceAndFailoverCsharp from './_load-balance-and-failover-csharp.mdx'; -import LoadBalanceAndFailoverJava from './_load-balance-and-failover-java.mdx'; -import LoadBalanceAndFailoverNodejs from './_load-balance-and-failover-nodejs.mdx'; +import LoadBalanceAndFailoverCsharp from './content/_load-balance-and-failover-csharp.mdx'; +import LoadBalanceAndFailoverJava from './content/_load-balance-and-failover-java.mdx'; +import LoadBalanceAndFailoverNodejs from './content/_load-balance-and-failover-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/querying.mdx b/versioned_docs/version-4.1/client-api/configuration/querying.mdx index c758060e9b..f5bb516607 100644 --- a/versioned_docs/version-4.1/client-api/configuration/querying.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/configuration/serialization.mdx b/versioned_docs/version-4.1/client-api/configuration/serialization.mdx index 7b97467d9e..f531b1b2d0 100644 --- a/versioned_docs/version-4.1/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-4.1/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-4.1/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-4.1/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/_creating-document-store-java.mdx b/versioned_docs/version-4.1/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-4.1/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-4.1/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-4.1/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-4.1/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-4.1/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-4.1/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-4.1/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-4.1/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-4.1/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-4.1/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-4.1/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/creating-document-store.mdx b/versioned_docs/version-4.1/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-4.1/client-api/creating-document-store.mdx +++ b/versioned_docs/version-4.1/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index bcc8c85ea4..483a687210 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d296754727..46beae2231 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 00e96e6291..09a0baf74b 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/api-overview.mdx index 9c83a26b01..eb4bf61b9e 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_api-overview-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_api-overview-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_api-overview-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_examples-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_examples-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_examples-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-4.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/examples.mdx index e742ab8d09..6c436e4c76 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-4.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-4.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-4.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-java.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-java.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-java.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-java.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-java.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-java.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-nodejs.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/document-identifiers/_working-with-document-identifiers-nodejs.mdx rename to versioned_docs/version-4.1/client-api/document-identifiers/content/_working-with-document-identifiers-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/hilo-algorithm.mdx index 0ce06ebcfa..e0474c9454 100644 --- a/versioned_docs/version-4.1/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-4.1/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; -import HiloAlgorithmJava from './_hilo-algorithm-java.mdx'; -import HiloAlgorithmNodejs from './_hilo-algorithm-nodejs.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmJava from './content/_hilo-algorithm-java.mdx'; +import HiloAlgorithmNodejs from './content/_hilo-algorithm-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-4.1/client-api/document-identifiers/working-with-document-identifiers.mdx index 8b3dfc0b15..b81b004af2 100644 --- a/versioned_docs/version-4.1/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-4.1/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; -import WorkingWithDocumentIdentifiersJava from './_working-with-document-identifiers-java.mdx'; -import WorkingWithDocumentIdentifiersNodejs from './_working-with-document-identifiers-nodejs.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersJava from './content/_working-with-document-identifiers-java.mdx'; +import WorkingWithDocumentIdentifiersNodejs from './content/_working-with-document-identifiers-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-4.1/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-4.1/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-4.1/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-4.1/client-api/how-to/handle-document-relationships.mdx index 9c633ad5a9..b20ad2dcab 100644 --- a/versioned_docs/version-4.1/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-4.1/client-api/how-to/handle-document-relationships.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-4.1/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-4.1/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-4.1/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-4.1/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-4.1/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-4.1/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/net-client-versions.mdx b/versioned_docs/version-4.1/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-4.1/client-api/net-client-versions.mdx +++ b/versioned_docs/version-4.1/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-4.1/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-4.1/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-4.1/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-4.1/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-4.1/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-4.1/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-4.1/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-4.1/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-4.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-4.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-4.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 44907a01a9..8b9780aee1 100644 --- a/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index a7d32b6528..27f60b056c 100644 --- a/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-4.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/overview.mdx index 06412b791f..bd1ec58ac8 100644 --- a/versioned_docs/version-4.1/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-4.1/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-4.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-4.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-4.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/_delete-by-query-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/_delete-by-query-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/_delete-by-query-java.mdx b/versioned_docs/version-4.1/client-api/operations/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/_delete-by-query-java.mdx rename to versioned_docs/version-4.1/client-api/operations/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-4.1/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-4.1/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-4.1/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-4.1/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-4.1/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-4.1/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-4.1/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-4.1/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-4.1/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-4.1/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-4.1/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-4.1/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/delete-by-query.mdx b/versioned_docs/version-4.1/client-api/operations/delete-by-query.mdx index fa8a8b681d..50bc2515e9 100644 --- a/versioned_docs/version-4.1/client-api/operations/delete-by-query.mdx +++ b/versioned_docs/version-4.1/client-api/operations/delete-by-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-4.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-4.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-4.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 8b3e793df4..d066d2eb37 100644 --- a/versioned_docs/version-4.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-4.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 960030cb78..f3bc0e847d 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx index fd66f74e2b..1be313d638 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index da2a18bd7c..217f4c083c 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; -import AddConnectionStringJava from './_add-connection-string-java.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; +import AddConnectionStringJava from './content/_add-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 365c692f3c..b2d4644259 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; -import GetConnectionStringJava from './_get-connection-string-java.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; +import GetConnectionStringJava from './content/_get-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index b69ef679d2..0ffe4f8a0e 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; -import RemoveConnectionStringJava from './_remove-connection-string-java.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringJava from './content/_remove-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-collection-statistics-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-collection-statistics-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-detailed-statistics-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-detailed-statistics-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-statistics-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-statistics-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-statistics-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/_get-statistics-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/_get-statistics-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/content/_get-statistics-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/add-etl.mdx index 6b370645b3..990b55c005 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/get-collection-statistics.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/get-collection-statistics.mdx index ac33eb1e8a..aa9d87c7ce 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/get-collection-statistics.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/get-collection-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCollectionStatisticsCsharp from './_get-collection-statistics-csharp.mdx'; -import GetCollectionStatisticsJava from './_get-collection-statistics-java.mdx'; +import GetCollectionStatisticsCsharp from './content/_get-collection-statistics-csharp.mdx'; +import GetCollectionStatisticsJava from './content/_get-collection-statistics-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/get-detailed-statistics.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/get-detailed-statistics.mdx index 80e4f039ba..c9b4936927 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/get-detailed-statistics.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/get-detailed-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDetailedStatisticsCsharp from './_get-detailed-statistics-csharp.mdx'; -import GetDetailedStatisticsJava from './_get-detailed-statistics-java.mdx'; +import GetDetailedStatisticsCsharp from './content/_get-detailed-statistics-csharp.mdx'; +import GetDetailedStatisticsJava from './content/_get-detailed-statistics-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/get-statistics.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/get-statistics.mdx index 7ab59532a6..281d3a0a84 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/get-statistics.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/get-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatisticsCsharp from './_get-statistics-csharp.mdx'; -import GetStatisticsJava from './_get-statistics-java.mdx'; +import GetStatisticsCsharp from './content/_get-statistics-csharp.mdx'; +import GetStatisticsJava from './content/_get-statistics-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/identities/get-identities.mdx index 3815c90caf..6d6de5138a 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-4.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/delete-index.mdx index b7de8fa9ea..d31358936f 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/disable-index.mdx index 0c5806cf4d..6c084fd5d4 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/enable-index.mdx index 6506876348..4a238c903e 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-errors.mdx index 677b5cff6c..1f167fa168 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-names.mdx index b2335e394f..b5ae1f846f 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index.mdx index a3c77a8ac9..2a43d3f84c 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-indexes.mdx index e6179f273c..2b73a09b0d 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-terms.mdx index 1bf8971406..e76ea582dd 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/index-has-changed.mdx index 1662b2d172..7f88cbc329 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/put-indexes.mdx index 742060167b..aec419ba4e 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/reset-index.mdx index 6171b19111..034cae96a8 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-lock.mdx index a38fcd9e29..de6e64089e 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-priority.mdx index c186cbbb2a..eaf94b9e7b 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-index.mdx index 6f9fd53715..e5de41e7ca 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-indexing.mdx index 01a0c2a0e5..12c1cadfc5 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-index.mdx index bc0a9a5470..b672d7c320 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-indexing.mdx index f0d62c3000..d8186af3a8 100644 --- a/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-4.1/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-4.1/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-4.1/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-4.1/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-4.1/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/patching/set-based.mdx b/versioned_docs/version-4.1/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-4.1/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-4.1/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/patching/single-document.mdx b/versioned_docs/version-4.1/client-api/operations/patching/single-document.mdx index 096bfb338a..f9984f85f9 100644 --- a/versioned_docs/version-4.1/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-4.1/client-api/operations/patching/single-document.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/revisions/configure-revisions.mdx b/versioned_docs/version-4.1/client-api/operations/revisions/configure-revisions.mdx index 54470ca110..09a3f0e967 100644 --- a/versioned_docs/version-4.1/client-api/operations/revisions/configure-revisions.mdx +++ b/versioned_docs/version-4.1/client-api/operations/revisions/configure-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/revisions/_configure-revisions-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/revisions/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/revisions/_configure-revisions-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/revisions/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/revisions/_configure-revisions-java.mdx b/versioned_docs/version-4.1/client-api/operations/revisions/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/revisions/_configure-revisions-java.mdx rename to versioned_docs/version-4.1/client-api/operations/revisions/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/add-database-node.mdx index 2cb4d31d60..b9fe604e59 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/add-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx index aee0d3102b..e9118cf383 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/delete-certificate.mdx index f916163c53..a533d68ca2 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx index 2527bf1aff..047f33765b 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/compact-database.mdx index ed8832538e..696f5a0b6c 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/compact-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseJava from './_compact-database-java.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseJava from './content/_compact-database-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index 3042e7dc25..3137e56b18 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index c474bd59a1..14126836c5 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_compact-database-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_compact-database-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_compact-database-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_compact-database-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/create-database.mdx index abd4d68c0d..ea75a81467 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-4.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/promote-database-node.mdx index a1b342c55a..14e10ef548 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/restore-backup.mdx index 0a28a9ca56..122865eee3 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/restore-backup.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-4.1/client-api/operations/server-wide/toggle-databases-state.mdx index 61b9d9a396..fd4c1e4e85 100644 --- a/versioned_docs/version-4.1/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-4.1/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/operations/what-are-operations.mdx b/versioned_docs/version-4.1/client-api/operations/what-are-operations.mdx index 7c2ad27db8..9f02c7218e 100644 --- a/versioned_docs/version-4.1/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-4.1/client-api/operations/what-are-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_deleting-csharp.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_deleting-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_deleting-java.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_deleting-java.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_deleting-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_loading-csharp.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_loading-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_loading-java.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_loading-java.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_storing-csharp.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_storing-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_storing-java.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_storing-java.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_storing-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_storing-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/attachments/copying-moving-renaming.mdx b/versioned_docs/version-4.1/client-api/session/attachments/copying-moving-renaming.mdx index 99de0ae4c8..22f992e1d0 100644 --- a/versioned_docs/version-4.1/client-api/session/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-4.1/client-api/session/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/attachments/deleting.mdx b/versioned_docs/version-4.1/client-api/session/attachments/deleting.mdx index 3433931530..9470a16e40 100644 --- a/versioned_docs/version-4.1/client-api/session/attachments/deleting.mdx +++ b/versioned_docs/version-4.1/client-api/session/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/attachments/loading.mdx b/versioned_docs/version-4.1/client-api/session/attachments/loading.mdx index 2acde9fdac..57c19032be 100644 --- a/versioned_docs/version-4.1/client-api/session/attachments/loading.mdx +++ b/versioned_docs/version-4.1/client-api/session/attachments/loading.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/attachments/storing.mdx b/versioned_docs/version-4.1/client-api/session/attachments/storing.mdx index 2861d1ad25..47022f1708 100644 --- a/versioned_docs/version-4.1/client-api/session/attachments/storing.mdx +++ b/versioned_docs/version-4.1/client-api/session/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/attachments/what-are-attachments.mdx b/versioned_docs/version-4.1/client-api/session/attachments/what-are-attachments.mdx index f8d3bea98c..17b91b137b 100644 --- a/versioned_docs/version-4.1/client-api/session/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-4.1/client-api/session/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-tracking-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-tracking-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-disable-tracking-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-disable-tracking-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-tracking.mdx index 81bd1835bb..3735376c95 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingJava from './_how-to-disable-tracking-java.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingJava from './content/_how-to-disable-tracking-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-4.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-4.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-4.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-4.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-4.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-4.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_create-or-modify-java.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_create-or-modify-java.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_delete-csharp.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_delete-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_delete-java.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_delete-java.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_overview-csharp.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_overview-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_overview-java.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_overview-java.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-4.1/client-api/session/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-4.1/client-api/session/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/counters/counters-and-other-features.mdx b/versioned_docs/version-4.1/client-api/session/counters/counters-and-other-features.mdx index bb6ecdf83a..a8bed052da 100644 --- a/versioned_docs/version-4.1/client-api/session/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-4.1/client-api/session/counters/counters-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/counters/create-or-modify.mdx b/versioned_docs/version-4.1/client-api/session/counters/create-or-modify.mdx index 9926c401a6..4fcbd6f430 100644 --- a/versioned_docs/version-4.1/client-api/session/counters/create-or-modify.mdx +++ b/versioned_docs/version-4.1/client-api/session/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/counters/delete.mdx b/versioned_docs/version-4.1/client-api/session/counters/delete.mdx index 57486f37e2..19f0c9e637 100644 --- a/versioned_docs/version-4.1/client-api/session/counters/delete.mdx +++ b/versioned_docs/version-4.1/client-api/session/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/counters/overview.mdx b/versioned_docs/version-4.1/client-api/session/counters/overview.mdx index e3f2e7dc98..520cdd444d 100644 --- a/versioned_docs/version-4.1/client-api/session/counters/overview.mdx +++ b/versioned_docs/version-4.1/client-api/session/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/counters/retrieve-counter-values.mdx b/versioned_docs/version-4.1/client-api/session/counters/retrieve-counter-values.mdx index f876091f0b..d52393ec25 100644 --- a/versioned_docs/version-4.1/client-api/session/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-4.1/client-api/session/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/deleting-entities.mdx b/versioned_docs/version-4.1/client-api/session/deleting-entities.mdx index 7830ac0cba..5d7364f947 100644 --- a/versioned_docs/version-4.1/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-4.1/client-api/session/how-to/check-if-attachment-exists.mdx index a87cd5c6dc..ac371e05a6 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-4.1/client-api/session/how-to/check-if-document-exists.mdx index f65fc256df..100f8f8655 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/check-if-document-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-4.1/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-4.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-4.1/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-4.1/client-api/session/how-to/defer-operations.mdx index e126593869..dd839bc6af 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-4.1/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-counters.mdx index bb4c0c5293..65488aa1a6 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-counters.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-4.1/client-api/session/how-to/ignore-entity-changes.mdx index ec0fea1629..d46a577949 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-4.1/client-api/session/how-to/perform-operations-lazily.mdx index a58c0c1d16..1e12e4cd05 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyJava from './_perform-operations-lazily-java.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyJava from './content/_perform-operations-lazily-java.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-4.1/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-4.1/client-api/session/how-to/subscribe-to-events.mdx index 590fa0e3b9..fab422008b 100644 --- a/versioned_docs/version-4.1/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-4.1/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/loading-entities.mdx b/versioned_docs/version-4.1/client-api/session/loading-entities.mdx index 2a39a6fb00..8214ff7506 100644 --- a/versioned_docs/version-4.1/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/opening-a-session.mdx b/versioned_docs/version-4.1/client-api/session/opening-a-session.mdx index 0b2921a7fa..bf2464701a 100644 --- a/versioned_docs/version-4.1/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-4.1/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 90b70a1b8f..0000000000 --- a/versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# How to Filter by Non-Existing Field - - -* There are situations where over time new fields are added to documents. - You may need to create a list of all of the documents that don't have these fields. - * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) - to add the missing fields. - -* To find documents with a missing field you can either: - * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) - * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) - - - -## Query a Static Index - -You can search for documents with missing fields by using a static index if it indexes the field which is -suspected to be missing in some of the documents. - -The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. - -* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, - query an index that indexes the fields `Freight` and `Id`. -* If your static index does not contain the desired field, either - * Modify your index definition to index the specific field. (This will trigger re-indexing.) - * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). - -### Example: Query a Static Index - -In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. - -#### First we need an index that includes `Freight` and a field that exists in every document - -We index the missing field `Freight` and the field `Id`, which exists in every document. -This way, the index includes all of the documents in the collection, -including those that are missing the specified field. - - - -{`// Create or modify a static index called Orders_ByFreight -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public Orders_ByFreight() - \{ - // Specify collection name - Map = orders => from doc in orders - select new - \{ - // Field that is missing in some documents - doc.Freight, - // Field that exists in all documents - doc.Id - \}; - \} -\} -`} - - - -#### Then we query the index to find documents where the field does not exist - -SAMPLE QUERY: - -Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. - - - - -{`List results = session - .Advanced - // Query the static index - .DocumentQuery() - // Verify that the index is not stale (optional) - .WaitForNonStaleResults(TimeSpan.MaxValue) - // Negate the next method - .Not - // Specify the field that is suspected to be missing - .WhereExists(x => x.Freight) - .ToList(); - // \`results\` will contain the list of incomplete documents. -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - -LINQ SYNTAX: - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **TIndexCreator** | string | The name of the index that you want to use. | -| **missingFieldName**| string | The field that is missing in some of the documents. | - - - - -## Query the Collection to Create an Auto-Index - -Another option is to query the collection for the missing field. -This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. - -See the example and query syntax descriptions below: - -### Example: A query that creates an Auto-Index - -The following query will create an auto-index on the "Freight" field -that is missing in some documents in the Orders collection. -The query result will contain all documents that do not have this field. - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("Freight") - .ToList(); -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - -#### LINQ Query Syntax - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **missingFieldName** | string | The field that is missing in some of the documents. | - - - - - -## Use Studio to filter by non-existing field - -You can also use Studio to find missing fields with an RQL query such as: - -``` -from "Orders" -where exists("Company") and not exists("Freight") -``` - -In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. -Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), -we must first call a field that exists in every document in the collection -and then the field that does not exist in some of them. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu items. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created for this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not have the specified field. - (The field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx deleted file mode 100644 index 0f91fcff74..0000000000 --- a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx +++ /dev/null @@ -1,487 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - -## Spatial - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | string | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | - -### DynamicSpatialFieldFactory - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | string | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in index | -| **fieldName** | string | Path to spatial field in index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | string | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | string | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | string | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx deleted file mode 100644 index 9c5caf9969..0000000000 --- a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..68ea5e01e7 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# How to Filter by Non-Existing Field + + +* There are situations where over time new fields are added to documents. + You may need to create a list of all of the documents that don't have these fields. + * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) + to add the missing fields. + +* To find documents with a missing field you can either: + * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) + * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) + + + +## Query a Static Index + +You can search for documents with missing fields by using a static index if it indexes the field which is +suspected to be missing in some of the documents. + +The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. + +* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, + query an index that indexes the fields `Freight` and `Id`. +* If your static index does not contain the desired field, either + * Modify your index definition to index the specific field. (This will trigger re-indexing.) + * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). + +### Example: Query a Static Index + +In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. + +#### First we need an index that includes `Freight` and a field that exists in every document + +We index the missing field `Freight` and the field `Id`, which exists in every document. +This way, the index includes all of the documents in the collection, +including those that are missing the specified field. + + + +{`// Create or modify a static index called Orders_ByFreight +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public Orders_ByFreight() + \{ + // Specify collection name + Map = orders => from doc in orders + select new + \{ + // Field that is missing in some documents + doc.Freight, + // Field that exists in all documents + doc.Id + \}; + \} +\} +`} + + + +#### Then we query the index to find documents where the field does not exist + +SAMPLE QUERY: + +Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. + + + + +{`List results = session + .Advanced + // Query the static index + .DocumentQuery() + // Verify that the index is not stale (optional) + .WaitForNonStaleResults(TimeSpan.MaxValue) + // Negate the next method + .Not + // Specify the field that is suspected to be missing + .WhereExists(x => x.Freight) + .ToList(); + // \`results\` will contain the list of incomplete documents. +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + +LINQ SYNTAX: + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **TIndexCreator** | string | The name of the index that you want to use. | +| **missingFieldName**| string | The field that is missing in some of the documents. | + + + + +## Query the Collection to Create an Auto-Index + +Another option is to query the collection for the missing field. +This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. + +See the example and query syntax descriptions below: + +### Example: A query that creates an Auto-Index + +The following query will create an auto-index on the "Freight" field +that is missing in some documents in the Orders collection. +The query result will contain all documents that do not have this field. + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("Freight") + .ToList(); +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + +#### LINQ Query Syntax + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **missingFieldName** | string | The field that is missing in some of the documents. | + + + + + +## Use Studio to filter by non-existing field + +You can also use Studio to find missing fields with an RQL query such as: + +``` +from "Orders" +where exists("Company") and not exists("Freight") +``` + +In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. +Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), +we must first call a field that exists in every document in the collection +and then the field that does not exist in some of them. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu items. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created for this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not have the specified field. + (The field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-proximity-search-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-proximity-search-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx new file mode 100644 index 0000000000..75c0896083 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx @@ -0,0 +1,487 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + +## Spatial + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | string | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | + +### DynamicSpatialFieldFactory + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | string | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in index | +| **fieldName** | string | Path to spatial field in index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | string | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | string | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | string | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx new file mode 100644 index 0000000000..2396725492 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-fuzzy-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-fuzzy-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-regex-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index a64e783cc2..0000000000 --- a/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery Timings(out QueryTimings timings); -`} - - - -## Example - - - - -{`var resultWithTimings = session.Advanced.DocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToList(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToListAsync(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index a85ad6f470..0000000000 --- a/versioned_docs/version-4.1/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..b777106c96 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,57 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery Timings(out QueryTimings timings); +`} + + + +## Example + + + + +{`var resultWithTimings = session.Advanced.DocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToList(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToListAsync(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..99f3fa91d6 --- /dev/null +++ b/versioned_docs/version-4.1/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/include-explanations.mdx index ec808ee6a9..4df35b7773 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/debugging/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-4.1/client-api/session/querying/debugging/query-timings.mdx index 945f73958f..7986688800 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/debugging/query-timings.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-4.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-4.1/client-api/session/querying/document-query/what-is-document-query.mdx index cef08c1c05..798546d402 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-customize-query.mdx index 2e9f4cd49b..d8110e41f3 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-field.mdx index f0ff8185c2..285ee08861 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 38b64f0c4f..d194cb8bcf 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-get-query-statistics.mdx index 83a9c90774..433e7bbfad 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx index e715a770b3..1b6695fbca 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-proximity-search.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-proximity-search.mdx index ddaa663299..622e2335b3 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-proximity-search.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-proximity-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProximitySearchCsharp from './_how-to-perform-proximity-search-csharp.mdx'; -import HowToPerformProximitySearchJava from './_how-to-perform-proximity-search-java.mdx'; +import HowToPerformProximitySearchCsharp from './content/_how-to-perform-proximity-search-csharp.mdx'; +import HowToPerformProximitySearchJava from './content/_how-to-perform-proximity-search-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-queries-lazily.mdx index e32d80e161..81bbc4fa19 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-project-query-results.mdx index 4064387648..9c7d07ff5c 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-query-a-spatial-index.mdx index a61668f911..2a328088f5 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-query-with-exact-match.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-query-with-exact-match.mdx index 29dadbe6eb..c6befd9e24 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-query-with-exact-match.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-query-with-exact-match.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryWithExactMatchCsharp from './_how-to-query-with-exact-match-csharp.mdx'; -import HowToQueryWithExactMatchJava from './_how-to-query-with-exact-match-java.mdx'; -import HowToQueryWithExactMatchNodejs from './_how-to-query-with-exact-match-nodejs.mdx'; +import HowToQueryWithExactMatchCsharp from './content/_how-to-query-with-exact-match-csharp.mdx'; +import HowToQueryWithExactMatchJava from './content/_how-to-query-with-exact-match-java.mdx'; +import HowToQueryWithExactMatchNodejs from './content/_how-to-query-with-exact-match-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-query.mdx index e62fb53f99..73070cca5b 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryJava from './_how-to-query-java.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryJava from './content/_how-to-query-java.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-stream-query-results.mdx index 75d86a60b2..69bde8d43d 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-fuzzy.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-fuzzy.mdx index 1b18017dcb..9d2276243c 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-fuzzy.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-fuzzy.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseFuzzyCsharp from './_how-to-use-fuzzy-csharp.mdx'; -import HowToUseFuzzyJava from './_how-to-use-fuzzy-java.mdx'; +import HowToUseFuzzyCsharp from './content/_how-to-use-fuzzy-csharp.mdx'; +import HowToUseFuzzyJava from './content/_how-to-use-fuzzy-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-highlighting.mdx index 93ef8a0c20..a03a38aeea 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-regex.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-regex.mdx index d46f82cab1..e0e9f41896 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-regex.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseRegexCsharp from './_how-to-use-regex-csharp.mdx'; -import HowToUseRegexJava from './_how-to-use-regex-java.mdx'; -import HowToUseRegexNodejs from './_how-to-use-regex-nodejs.mdx'; +import HowToUseRegexCsharp from './content/_how-to-use-regex-csharp.mdx'; +import HowToUseRegexJava from './content/_how-to-use-regex-java.mdx'; +import HowToUseRegexNodejs from './content/_how-to-use-regex-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-search.mdx index 8e128dfebb..eab93a36f4 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-use-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-4.1/client-api/session/querying/how-to-work-with-suggestions.mdx index 35155f00e2..b73a402884 100644 --- a/versioned_docs/version-4.1/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-4.1/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_counter-revisions-csharp.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_counter-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_counter-revisions-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_counter-revisions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_counter-revisions-java.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_counter-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_counter-revisions-java.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_counter-revisions-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-4.1/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-4.1/client-api/session/revisions/counter-revisions.mdx b/versioned_docs/version-4.1/client-api/session/revisions/counter-revisions.mdx index 2685ffaefe..096cb444a7 100644 --- a/versioned_docs/version-4.1/client-api/session/revisions/counter-revisions.mdx +++ b/versioned_docs/version-4.1/client-api/session/revisions/counter-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterRevisionsCsharp from './_counter-revisions-csharp.mdx'; -import CounterRevisionsJava from './_counter-revisions-java.mdx'; +import CounterRevisionsCsharp from './content/_counter-revisions-csharp.mdx'; +import CounterRevisionsJava from './content/_counter-revisions-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/revisions/loading.mdx b/versioned_docs/version-4.1/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-4.1/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-4.1/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-4.1/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-4.1/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-4.1/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/saving-changes.mdx b/versioned_docs/version-4.1/client-api/session/saving-changes.mdx index b2f757ca4c..190869532f 100644 --- a/versioned_docs/version-4.1/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-4.1/client-api/session/saving-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/storing-entities.mdx b/versioned_docs/version-4.1/client-api/session/storing-entities.mdx index 09787c1800..dafb1abe29 100644 --- a/versioned_docs/version-4.1/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/updating-entities.mdx b/versioned_docs/version-4.1/client-api/session/updating-entities.mdx index c7a719d596..58a56a1004 100644 --- a/versioned_docs/version-4.1/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-4.1/client-api/session/updating-entities.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-4.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx index 1eb9ad91cf..c17516971d 100644 --- a/versioned_docs/version-4.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-4.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-4.1/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-4.1/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-4.1/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-4.1/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/setting-up-default-database.mdx b/versioned_docs/version-4.1/client-api/setting-up-default-database.mdx index 75fc4c2450..b217f301b3 100644 --- a/versioned_docs/version-4.1/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-4.1/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-4.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-4.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-4.1/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-4.1/client-api/smuggler/what-is-smuggler.mdx index 69f2bb730f..1ebc89258e 100644 --- a/versioned_docs/version-4.1/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-4.1/client-api/smuggler/what-is-smuggler.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; diff --git a/versioned_docs/version-4.1/client-api/what-is-a-document-store.mdx b/versioned_docs/version-4.1/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-4.1/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-4.1/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-4.1/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-4.1/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-4.1/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_index-query-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_index-query-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_query-result-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_query-result-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/_stream-result-csharp.mdx b/versioned_docs/version-4.1/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-4.1/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-4.1/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-4.1/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-4.1/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/counters-batch-command-data.mdx b/versioned_docs/version-4.1/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-4.1/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/delete-command-data.mdx b/versioned_docs/version-4.1/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-4.1/glossary/delete-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-4.1/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-4.1/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/index-query.mdx b/versioned_docs/version-4.1/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-4.1/glossary/index-query.mdx +++ b/versioned_docs/version-4.1/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/move-attachment-command-data.mdx b/versioned_docs/version-4.1/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-4.1/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/patch-command-data.mdx b/versioned_docs/version-4.1/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-4.1/glossary/patch-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/put-command-data.mdx b/versioned_docs/version-4.1/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-4.1/glossary/put-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-4.1/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-4.1/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-4.1/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/query-result.mdx b/versioned_docs/version-4.1/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-4.1/glossary/query-result.mdx +++ b/versioned_docs/version-4.1/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/stream-query-statistics.mdx b/versioned_docs/version-4.1/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-4.1/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-4.1/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-4.1/glossary/stream-result.mdx b/versioned_docs/version-4.1/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-4.1/glossary/stream-result.mdx +++ b/versioned_docs/version-4.1/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-4.1/indexes/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/_fanout-indexes-csharp.mdx deleted file mode 100644 index 94f6065246..0000000000 --- a/versioned_docs/version-4.1/indexes/_fanout-indexes-csharp.mdx +++ /dev/null @@ -1,171 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public class Orders_ByProduct : AbstractIndexCreationTask -{ - public Orders_ByProduct() - { - Map = orders => from order in orders - from orderLine in order.Lines - select new - { - orderLine.Product, - orderLine.ProductName - }; - } -} -`} - - - - -{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByProduct() - { - Maps = new HashSet - { - @"map('Orders', function (order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - ProductName: l.ProductName - }) - }); - return res; - })", - }; - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public class Product_Sales : AbstractIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - public int Count { get; set; } - public decimal Total; - } - - public Product_Sales() - { - Map = orders => from order in orders - from line in order.Lines - select new Result - { - Product = line.Product, - Count = 1, - Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) - }; - - Reduce = results => from result in results - group result by result.Product - into g - select new - { - Product = g.Key, - Count = g.Sum(x => x.Count), - Total = g.Sum(x => x.Total) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.1/indexes/_fanout-indexes-java.mdx b/versioned_docs/version-4.1/indexes/_fanout-indexes-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-4.1/indexes/_fanout-indexes-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-4.1/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.1/indexes/boosting.mdx b/versioned_docs/version-4.1/indexes/boosting.mdx index 63937b73b3..4e299192ad 100644 --- a/versioned_docs/version-4.1/indexes/boosting.mdx +++ b/versioned_docs/version-4.1/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/_boosting-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_boosting-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_boosting-java.mdx b/versioned_docs/version-4.1/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_boosting-java.mdx rename to versioned_docs/version-4.1/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_boosting-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-4.1/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-4.1/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_extending-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/content/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_fanout-indexes-csharp.mdx new file mode 100644 index 0000000000..bb8d3382d9 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/content/_fanout-indexes-csharp.mdx @@ -0,0 +1,171 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public class Orders_ByProduct : AbstractIndexCreationTask +{ + public Orders_ByProduct() + { + Map = orders => from order in orders + from orderLine in order.Lines + select new + { + orderLine.Product, + orderLine.ProductName + }; + } +} +`} + + + + +{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByProduct() + { + Maps = new HashSet + { + @"map('Orders', function (order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + ProductName: l.ProductName + }) + }); + return res; + })", + }; + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public class Product_Sales : AbstractIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + public int Count { get; set; } + public decimal Total; + } + + public Product_Sales() + { + Map = orders => from order in orders + from line in order.Lines + select new Result + { + Product = line.Product, + Count = 1, + Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) + }; + + Reduce = results => from result in results + group result by result.Product + into g + select new + { + Product = g.Key, + Count = g.Sum(x => x.Count), + Total = g.Sum(x => x.Total) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.1/indexes/content/_fanout-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_fanout-indexes-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/content/_fanout-indexes-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.1/indexes/_indexing-attachments-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-attachments-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-attachments-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-attachments-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-attachments-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-attachments-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-attachments-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-basics-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-counters-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-counters-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-counters-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-counters-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-counters-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-counters-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-counters-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-hierarchical-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-hierarchical-data-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-hierarchical-data-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.1/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-related-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-related-documents-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-related-documents-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-4.1/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-4.1/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_map-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_map-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-4.1/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-4.1/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_stale-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-4.1/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-4.1/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_using-dynamic-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-dynamic-fields-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_using-dynamic-fields-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-4.1/indexes/content/_using-dynamic-fields-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-dynamic-fields-java.mdx rename to versioned_docs/version-4.1/indexes/content/_using-dynamic-fields-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-4.1/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-4.1/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-4.1/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-4.1/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-4.1/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-4.1/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-4.1/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-4.1/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-4.1/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-4.1/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-4.1/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-4.1/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/creating-and-deploying.mdx b/versioned_docs/version-4.1/indexes/creating-and-deploying.mdx index 7207cc5780..e01dfd772e 100644 --- a/versioned_docs/version-4.1/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-4.1/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/extending-indexes.mdx b/versioned_docs/version-4.1/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-4.1/indexes/extending-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/fanout-indexes.mdx b/versioned_docs/version-4.1/indexes/fanout-indexes.mdx index c07252a661..c76c4ee85f 100644 --- a/versioned_docs/version-4.1/indexes/fanout-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/fanout-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FanoutIndexesCsharp from './_fanout-indexes-csharp.mdx'; -import FanoutIndexesJava from './_fanout-indexes-java.mdx'; +import FanoutIndexesCsharp from './content/_fanout-indexes-csharp.mdx'; +import FanoutIndexesJava from './content/_fanout-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-attachments.mdx b/versioned_docs/version-4.1/indexes/indexing-attachments.mdx index 97d164dc49..5f230632f4 100644 --- a/versioned_docs/version-4.1/indexes/indexing-attachments.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-attachments.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingAttachmentsCsharp from './_indexing-attachments-csharp.mdx'; -import IndexingAttachmentsJava from './_indexing-attachments-java.mdx'; +import IndexingAttachmentsCsharp from './content/_indexing-attachments-csharp.mdx'; +import IndexingAttachmentsJava from './content/_indexing-attachments-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-basics.mdx b/versioned_docs/version-4.1/indexes/indexing-basics.mdx index 72b153a25f..15560b37fc 100644 --- a/versioned_docs/version-4.1/indexes/indexing-basics.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-counters.mdx b/versioned_docs/version-4.1/indexes/indexing-counters.mdx index 6996054ad7..f73233fbfd 100644 --- a/versioned_docs/version-4.1/indexes/indexing-counters.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCountersCsharp from './_indexing-counters-csharp.mdx'; -import IndexingCountersJava from './_indexing-counters-java.mdx'; +import IndexingCountersCsharp from './content/_indexing-counters-csharp.mdx'; +import IndexingCountersJava from './content/_indexing-counters-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-4.1/indexes/indexing-hierarchical-data.mdx index ebe167fdaa..b0481950bf 100644 --- a/versioned_docs/version-4.1/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-hierarchical-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-4.1/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-4.1/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-4.1/indexes/indexing-polymorphic-data.mdx index bddb362a3a..4c08de81be 100644 --- a/versioned_docs/version-4.1/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-related-documents.mdx b/versioned_docs/version-4.1/indexes/indexing-related-documents.mdx index 528f4459ea..b8cec71b26 100644 --- a/versioned_docs/version-4.1/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-related-documents.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/indexing-spatial-data.mdx b/versioned_docs/version-4.1/indexes/indexing-spatial-data.mdx index 7f0511363d..caca7442e3 100644 --- a/versioned_docs/version-4.1/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-4.1/indexes/indexing-spatial-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/javascript-indexes.mdx b/versioned_docs/version-4.1/indexes/javascript-indexes.mdx index 7317155649..44909a2261 100644 --- a/versioned_docs/version-4.1/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/map-indexes.mdx b/versioned_docs/version-4.1/indexes/map-indexes.mdx index 6ce9d3ff78..d388490e24 100644 --- a/versioned_docs/version-4.1/indexes/map-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/map-reduce-indexes.mdx b/versioned_docs/version-4.1/indexes/map-reduce-indexes.mdx index 11f019596e..71f0f9935c 100644 --- a/versioned_docs/version-4.1/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/map-reduce-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/multi-map-indexes.mdx b/versioned_docs/version-4.1/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-4.1/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 01b66b3e5d..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,349 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **Cost** field, return the count of the following ranges: - - * Cost < 200.0 - * 200.0 <= Cost < 400.0 - * 400.0 <= Cost < 600.0 - * 600.0 <= Cost < 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels < 7.0 - * 7.0 <= Megapixels < 10.0 - * Megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "Manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "Cost", - "Values": [ - \{ - "Count": 6, - "Range": "Cost <= 200" - \}, - \{ - "Count": 2, - "Range": "Cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "Cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "Cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "Cost >= 800" - \} - ] - \}, - \{ - "Name": "Megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "Megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "Megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "Megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "Megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.1/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-4.1/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 54c908d478..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.1/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 690e4df1df..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,312 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`export class Camera \{ - constructor(manufacturer, model, \{ - dateOfListing, - cost, - zoom, - megapixels, - imageStabilizer - \}) \{ - this.manufacturer = manufacturer; - this.model = model; - this.dateOfListing = dateOfListing; - this.cost = cost; - this.zoom = zoom; - this.megapixels = megapixels; - this.imageStabilizer = imageStabilizer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = \`from camera in docs.Cameras select new \{ - camera.manufacturer, - camera.model, - camera.cost, - camera.dateOfListing, - camera.megapixels - \}\`; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`const facetSetup = new FacetSetup(); -facetSetup.facets = facets; -facetSetup.rangeFacets = rangeFacets; - -await session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.1/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ecb4312302..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.1/indexes/querying/_paging-java.mdx b/versioned_docs/version-4.1/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-4.1/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index e52c0cff7a..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a Fanout index. - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.1/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/_spatial-csharp.mdx deleted file mode 100644 index b8e29cae09..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_spatial-csharp.mdx +++ /dev/null @@ -1,165 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `RelatesToShape` - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .Query() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`public class Events_ByCoordinates : AbstractIndexCreationTask -{ - public Events_ByCoordinates() - { - Map = events => from e in events - select new - { - Coordinates = CreateSpatialField(e.Latitude, e.Longitude) - }; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(Coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.1/indexes/querying/_spatial-java.mdx b/versioned_docs/version-4.1/indexes/querying/_spatial-java.mdx deleted file mode 100644 index 052325a8dc..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.1/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/_spatial-nodejs.mdx deleted file mode 100644 index 77542032c5..0000000000 --- a/versioned_docs/version-4.1/indexes/querying/_spatial-nodejs.mdx +++ /dev/null @@ -1,122 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape()` - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - "Within" - )) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`const results = await session - .query({ indexName: "Events/ByCoordinates" }) - .spatial("coordinates", - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`class Events_ByCoordinates extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Events.Select(e => new { - Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) - })\`; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.1/indexes/querying/basics.mdx b/versioned_docs/version-4.1/indexes/querying/basics.mdx index f1cbf38302..23f7507680 100644 --- a/versioned_docs/version-4.1/indexes/querying/basics.mdx +++ b/versioned_docs/version-4.1/indexes/querying/basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; -import BasicsNodejs from './_basics-nodejs.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; +import BasicsNodejs from './content/_basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/boosting.mdx b/versioned_docs/version-4.1/indexes/querying/boosting.mdx index 97dc2a028f..35a0a0b712 100644 --- a/versioned_docs/version-4.1/indexes/querying/boosting.mdx +++ b/versioned_docs/version-4.1/indexes/querying/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_basics-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_basics-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_basics-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_basics-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_basics-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_boosting-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_boosting-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_boosting-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_boosting-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_boosting-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_boosting-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_distinct-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..62e55bba88 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,349 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **Cost** field, return the count of the following ranges: + + * Cost < 200.0 + * 200.0 <= Cost < 400.0 + * 400.0 <= Cost < 600.0 + * 600.0 <= Cost < 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels < 7.0 + * 7.0 <= Megapixels < 10.0 + * Megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "Manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "Cost", + "Values": [ + \{ + "Count": 6, + "Range": "Cost <= 200" + \}, + \{ + "Count": 2, + "Range": "Cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "Cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "Cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "Cost >= 800" + \} + ] + \}, + \{ + "Name": "Megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "Megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "Megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "Megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "Megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..2dca93bfaf --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..2b4d199a3d --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,312 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`export class Camera \{ + constructor(manufacturer, model, \{ + dateOfListing, + cost, + zoom, + megapixels, + imageStabilizer + \}) \{ + this.manufacturer = manufacturer; + this.model = model; + this.dateOfListing = dateOfListing; + this.cost = cost; + this.zoom = zoom; + this.megapixels = megapixels; + this.imageStabilizer = imageStabilizer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = \`from camera in docs.Cameras select new \{ + camera.manufacturer, + camera.model, + camera.cost, + camera.dateOfListing, + camera.megapixels + \}\`; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`const facetSetup = new FacetSetup(); +facetSetup.facets = facets; +facetSetup.rangeFacets = rangeFacets; + +await session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.1/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_filtering-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_intersection-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..967fb68620 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2cc2e022a --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a Fanout index. + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.1/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_projections-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_projections-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_sorting-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/content/_spatial-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_spatial-csharp.mdx new file mode 100644 index 0000000000..1062993808 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_spatial-csharp.mdx @@ -0,0 +1,165 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `RelatesToShape` + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .Query() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`public class Events_ByCoordinates : AbstractIndexCreationTask +{ + public Events_ByCoordinates() + { + Map = events => from e in events + select new + { + Coordinates = CreateSpatialField(e.Latitude, e.Longitude) + }; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(Coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..9c11a03099 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.1/indexes/querying/content/_spatial-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_spatial-nodejs.mdx new file mode 100644 index 0000000000..9e318daef2 --- /dev/null +++ b/versioned_docs/version-4.1/indexes/querying/content/_spatial-nodejs.mdx @@ -0,0 +1,122 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape()` + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + "Within" + )) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`const results = await session + .query({ indexName: "Events/ByCoordinates" }) + .spatial("coordinates", + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`class Events_ByCoordinates extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Events.Select(e => new { + Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) + })\`; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.1/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-4.1/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-4.1/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-4.1/indexes/querying/content/_suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.1/indexes/querying/_suggestions-nodejs.mdx rename to versioned_docs/version-4.1/indexes/querying/content/_suggestions-nodejs.mdx diff --git a/versioned_docs/version-4.1/indexes/querying/distinct.mdx b/versioned_docs/version-4.1/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-4.1/indexes/querying/distinct.mdx +++ b/versioned_docs/version-4.1/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/faceted-search.mdx b/versioned_docs/version-4.1/indexes/querying/faceted-search.mdx index 642a2a77a5..b9e984e8b0 100644 --- a/versioned_docs/version-4.1/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-4.1/indexes/querying/faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/filtering.mdx b/versioned_docs/version-4.1/indexes/querying/filtering.mdx index c1c3bf3139..ba11c389e5 100644 --- a/versioned_docs/version-4.1/indexes/querying/filtering.mdx +++ b/versioned_docs/version-4.1/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/highlighting.mdx b/versioned_docs/version-4.1/indexes/querying/highlighting.mdx index caddfb8b7c..98d011b0fb 100644 --- a/versioned_docs/version-4.1/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-4.1/indexes/querying/highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/intersection.mdx b/versioned_docs/version-4.1/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-4.1/indexes/querying/intersection.mdx +++ b/versioned_docs/version-4.1/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/morelikethis.mdx b/versioned_docs/version-4.1/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-4.1/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-4.1/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/paging.mdx b/versioned_docs/version-4.1/indexes/querying/paging.mdx index 4a4f877127..1375a3d67e 100644 --- a/versioned_docs/version-4.1/indexes/querying/paging.mdx +++ b/versioned_docs/version-4.1/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/projections.mdx b/versioned_docs/version-4.1/indexes/querying/projections.mdx index f358bb4489..84724cf411 100644 --- a/versioned_docs/version-4.1/indexes/querying/projections.mdx +++ b/versioned_docs/version-4.1/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-4.1/indexes/querying/query-vs-document-query.mdx index b766203269..8d99869330 100644 --- a/versioned_docs/version-4.1/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-4.1/indexes/querying/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/searching.mdx b/versioned_docs/version-4.1/indexes/querying/searching.mdx index 2f747d4661..fb4145a63d 100644 --- a/versioned_docs/version-4.1/indexes/querying/searching.mdx +++ b/versioned_docs/version-4.1/indexes/querying/searching.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/sorting.mdx b/versioned_docs/version-4.1/indexes/querying/sorting.mdx index a230093906..fc72ce4f44 100644 --- a/versioned_docs/version-4.1/indexes/querying/sorting.mdx +++ b/versioned_docs/version-4.1/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/spatial.mdx b/versioned_docs/version-4.1/indexes/querying/spatial.mdx index 1e4e0092b9..5df771eb7a 100644 --- a/versioned_docs/version-4.1/indexes/querying/spatial.mdx +++ b/versioned_docs/version-4.1/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/querying/suggestions.mdx b/versioned_docs/version-4.1/indexes/querying/suggestions.mdx index 8e46c2ed39..d5209e47da 100644 --- a/versioned_docs/version-4.1/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-4.1/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/sorting-and-collation.mdx b/versioned_docs/version-4.1/indexes/sorting-and-collation.mdx index c55cbb45c0..f3c27ca9c0 100644 --- a/versioned_docs/version-4.1/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-4.1/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/stale-indexes.mdx b/versioned_docs/version-4.1/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-4.1/indexes/stale-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/storing-data-in-index.mdx b/versioned_docs/version-4.1/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-4.1/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-4.1/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/using-analyzers.mdx b/versioned_docs/version-4.1/indexes/using-analyzers.mdx index 5fb3468089..8b825fe9ba 100644 --- a/versioned_docs/version-4.1/indexes/using-analyzers.mdx +++ b/versioned_docs/version-4.1/indexes/using-analyzers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; diff --git a/versioned_docs/version-4.1/indexes/using-dynamic-fields.mdx b/versioned_docs/version-4.1/indexes/using-dynamic-fields.mdx index b35ee6b88e..b6d6b98cf2 100644 --- a/versioned_docs/version-4.1/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-4.1/indexes/using-dynamic-fields.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; diff --git a/versioned_docs/version-4.1/indexes/using-term-vectors.mdx b/versioned_docs/version-4.1/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-4.1/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-4.1/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/indexes/what-are-indexes.mdx b/versioned_docs/version-4.1/indexes/what-are-indexes.mdx index baeb219b47..613babe12e 100644 --- a/versioned_docs/version-4.1/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-4.1/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.1/server/_embedded-csharp.mdx b/versioned_docs/version-4.1/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/server/_embedded-csharp.mdx rename to versioned_docs/version-4.1/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-4.1/server/_embedded-java.mdx b/versioned_docs/version-4.1/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-4.1/server/_embedded-java.mdx rename to versioned_docs/version-4.1/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-4.1/server/embedded.mdx b/versioned_docs/version-4.1/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-4.1/server/embedded.mdx +++ b/versioned_docs/version-4.1/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-4.1/start/_test-driver-csharp.mdx b/versioned_docs/version-4.1/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-4.1/start/_test-driver-csharp.mdx rename to versioned_docs/version-4.1/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-4.1/start/_test-driver-java.mdx b/versioned_docs/version-4.1/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-4.1/start/_test-driver-java.mdx rename to versioned_docs/version-4.1/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-4.1/start/test-driver.mdx b/versioned_docs/version-4.1/start/test-driver.mdx index 9d0f4aa274..628fe56cec 100644 --- a/versioned_docs/version-4.1/start/test-driver.mdx +++ b/versioned_docs/version-4.1/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-4.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-4.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-4.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-4.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-4.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-4.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 9b8b55bb6a..dccbc4d7f4 100644 --- a/versioned_docs/version-4.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-4.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-4.2/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-4.2/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-4.2/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-4.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-4.2/client-api/changes/what-is-changes-api.mdx index 111608118f..c761eaa47b 100644 --- a/versioned_docs/version-4.2/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-4.2/client-api/changes/what-is-changes-api.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-4.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-4.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-4.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-4.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-4.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-4.2/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-4.2/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-4.2/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-4.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 5067204d77..d6621b1518 100644 --- a/versioned_docs/version-4.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-4.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-4.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-4.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-4.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index df8998788f..4c66bd534f 100644 --- a/versioned_docs/version-4.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-4.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-4.2/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/delete.mdx b/versioned_docs/version-4.2/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-4.2/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-4.2/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/commands/documents/get.mdx b/versioned_docs/version-4.2/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-4.2/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-4.2/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-4.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-4.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-4.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-4.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-4.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-4.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-4.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/commands/documents/put.mdx b/versioned_docs/version-4.2/client-api/commands/documents/put.mdx index 1178a97257..016c1f2cb7 100644 --- a/versioned_docs/version-4.2/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-4.2/client-api/commands/documents/put.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_conventions-java.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_conventions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_conventions-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_conventions-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-java.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-nodejs.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_load-balance-and-failover-nodejs.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_querying-java.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-4.2/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/conventions.mdx b/versioned_docs/version-4.2/client-api/configuration/conventions.mdx index f68ae0f3cd..9f1e23100f 100644 --- a/versioned_docs/version-4.2/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/conventions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsJava from './_conventions-java.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsJava from './content/_conventions-java.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-4.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-4.2/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/load-balance-and-failover.mdx b/versioned_docs/version-4.2/client-api/configuration/load-balance-and-failover.mdx index 6fcd694545..190894c2ec 100644 --- a/versioned_docs/version-4.2/client-api/configuration/load-balance-and-failover.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/load-balance-and-failover.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceAndFailoverCsharp from './_load-balance-and-failover-csharp.mdx'; -import LoadBalanceAndFailoverJava from './_load-balance-and-failover-java.mdx'; -import LoadBalanceAndFailoverNodejs from './_load-balance-and-failover-nodejs.mdx'; +import LoadBalanceAndFailoverCsharp from './content/_load-balance-and-failover-csharp.mdx'; +import LoadBalanceAndFailoverJava from './content/_load-balance-and-failover-java.mdx'; +import LoadBalanceAndFailoverNodejs from './content/_load-balance-and-failover-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/querying.mdx b/versioned_docs/version-4.2/client-api/configuration/querying.mdx index c758060e9b..f5bb516607 100644 --- a/versioned_docs/version-4.2/client-api/configuration/querying.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/configuration/serialization.mdx b/versioned_docs/version-4.2/client-api/configuration/serialization.mdx index 7b97467d9e..f531b1b2d0 100644 --- a/versioned_docs/version-4.2/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-4.2/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-4.2/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-4.2/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-4.2/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-4.2/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-4.2/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-4.2/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-4.2/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-4.2/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-4.2/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/creating-document-store.mdx b/versioned_docs/version-4.2/client-api/creating-document-store.mdx index c3703c0c2c..5132778fb7 100644 --- a/versioned_docs/version-4.2/client-api/creating-document-store.mdx +++ b/versioned_docs/version-4.2/client-api/creating-document-store.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index 545845e219..b9549d42f0 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d296754727..46beae2231 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 00e96e6291..09a0baf74b 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/api-overview.mdx index 8f1a50288a..82cc984c04 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-4.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/examples.mdx index ca8c2f97c2..d5c631951d 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/examples.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-4.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-4.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-4.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-java.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-java.mdx rename to versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-java.mdx diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/document-identifiers/_hilo-algorithm-nodejs.mdx rename to versioned_docs/version-4.2/client-api/document-identifiers/content/_hilo-algorithm-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-4.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/hilo-algorithm.mdx index 0ce06ebcfa..e0474c9454 100644 --- a/versioned_docs/version-4.2/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-4.2/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; -import HiloAlgorithmJava from './_hilo-algorithm-java.mdx'; -import HiloAlgorithmNodejs from './_hilo-algorithm-nodejs.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmJava from './content/_hilo-algorithm-java.mdx'; +import HiloAlgorithmNodejs from './content/_hilo-algorithm-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-4.2/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-4.2/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-4.2/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-4.2/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-4.2/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-4.2/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-4.2/client-api/how-to/handle-document-relationships.mdx index 9c633ad5a9..b20ad2dcab 100644 --- a/versioned_docs/version-4.2/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-4.2/client-api/how-to/handle-document-relationships.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-4.2/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-4.2/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-4.2/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-4.2/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-4.2/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-4.2/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/net-client-versions.mdx b/versioned_docs/version-4.2/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-4.2/client-api/net-client-versions.mdx +++ b/versioned_docs/version-4.2/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-4.2/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-4.2/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-4.2/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-4.2/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-4.2/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-4.2/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-4.2/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-4.2/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-4.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-4.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-4.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 44907a01a9..8b9780aee1 100644 --- a/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index a7d32b6528..27f60b056c 100644 --- a/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-4.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/overview.mdx index 06412b791f..bd1ec58ac8 100644 --- a/versioned_docs/version-4.2/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-4.2/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-4.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-4.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-4.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/_delete-by-query-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/_delete-by-query-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/_delete-by-query-java.mdx b/versioned_docs/version-4.2/client-api/operations/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/_delete-by-query-java.mdx rename to versioned_docs/version-4.2/client-api/operations/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-4.2/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-4.2/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-4.2/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-4.2/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-4.2/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-4.2/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-4.2/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-4.2/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-4.2/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-4.2/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-4.2/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-4.2/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/delete-by-query.mdx b/versioned_docs/version-4.2/client-api/operations/delete-by-query.mdx index fa8a8b681d..50bc2515e9 100644 --- a/versioned_docs/version-4.2/client-api/operations/delete-by-query.mdx +++ b/versioned_docs/version-4.2/client-api/operations/delete-by-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-4.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-4.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-4.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 8b3e793df4..d066d2eb37 100644 --- a/versioned_docs/version-4.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-4.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 960030cb78..f3bc0e847d 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx index fd66f74e2b..1be313d638 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index da2a18bd7c..217f4c083c 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; -import AddConnectionStringJava from './_add-connection-string-java.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; +import AddConnectionStringJava from './content/_add-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 365c692f3c..b2d4644259 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; -import GetConnectionStringJava from './_get-connection-string-java.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; +import GetConnectionStringJava from './content/_get-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index b69ef679d2..0ffe4f8a0e 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; -import RemoveConnectionStringJava from './_remove-connection-string-java.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringJava from './content/_remove-connection-string-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-collection-statistics-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-collection-statistics-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-detailed-statistics-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-detailed-statistics-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-statistics-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-statistics-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-statistics-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/_get-statistics-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/_get-statistics-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/content/_get-statistics-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/add-etl.mdx index 6b370645b3..990b55c005 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/get-collection-statistics.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/get-collection-statistics.mdx index ac33eb1e8a..aa9d87c7ce 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/get-collection-statistics.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/get-collection-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCollectionStatisticsCsharp from './_get-collection-statistics-csharp.mdx'; -import GetCollectionStatisticsJava from './_get-collection-statistics-java.mdx'; +import GetCollectionStatisticsCsharp from './content/_get-collection-statistics-csharp.mdx'; +import GetCollectionStatisticsJava from './content/_get-collection-statistics-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/get-detailed-statistics.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/get-detailed-statistics.mdx index 80e4f039ba..c9b4936927 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/get-detailed-statistics.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/get-detailed-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDetailedStatisticsCsharp from './_get-detailed-statistics-csharp.mdx'; -import GetDetailedStatisticsJava from './_get-detailed-statistics-java.mdx'; +import GetDetailedStatisticsCsharp from './content/_get-detailed-statistics-csharp.mdx'; +import GetDetailedStatisticsJava from './content/_get-detailed-statistics-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/get-statistics.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/get-statistics.mdx index 7ab59532a6..281d3a0a84 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/get-statistics.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/get-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatisticsCsharp from './_get-statistics-csharp.mdx'; -import GetStatisticsJava from './_get-statistics-java.mdx'; +import GetStatisticsCsharp from './content/_get-statistics-csharp.mdx'; +import GetStatisticsJava from './content/_get-statistics-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/identities/get-identities.mdx index 3815c90caf..6d6de5138a 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-4.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/delete-index.mdx index b7de8fa9ea..d31358936f 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/disable-index.mdx index 0c5806cf4d..6c084fd5d4 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/enable-index.mdx index 6506876348..4a238c903e 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-errors.mdx index 677b5cff6c..1f167fa168 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-names.mdx index b2335e394f..b5ae1f846f 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index.mdx index a3c77a8ac9..2a43d3f84c 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-indexes.mdx index e6179f273c..2b73a09b0d 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-terms.mdx index 1bf8971406..e76ea582dd 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/index-has-changed.mdx index 1662b2d172..7f88cbc329 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/put-indexes.mdx index 742060167b..aec419ba4e 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/reset-index.mdx index 6171b19111..034cae96a8 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-lock.mdx index a38fcd9e29..de6e64089e 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-priority.mdx index c186cbbb2a..eaf94b9e7b 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-index.mdx index 6f9fd53715..e5de41e7ca 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-indexing.mdx index 01a0c2a0e5..12c1cadfc5 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-index.mdx index bc0a9a5470..b672d7c320 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-indexing.mdx index f0d62c3000..d8186af3a8 100644 --- a/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-4.2/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-4.2/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-4.2/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/patching/set-based.mdx b/versioned_docs/version-4.2/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-4.2/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-4.2/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/patching/single-document.mdx b/versioned_docs/version-4.2/client-api/operations/patching/single-document.mdx index 6dc6e75272..b41b31d73b 100644 --- a/versioned_docs/version-4.2/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-4.2/client-api/operations/patching/single-document.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/revisions/configure-revisions.mdx b/versioned_docs/version-4.2/client-api/operations/revisions/configure-revisions.mdx index 54470ca110..09a3f0e967 100644 --- a/versioned_docs/version-4.2/client-api/operations/revisions/configure-revisions.mdx +++ b/versioned_docs/version-4.2/client-api/operations/revisions/configure-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/revisions/_configure-revisions-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/revisions/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/revisions/_configure-revisions-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/revisions/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/revisions/_configure-revisions-java.mdx b/versioned_docs/version-4.2/client-api/operations/revisions/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/revisions/_configure-revisions-java.mdx rename to versioned_docs/version-4.2/client-api/operations/revisions/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/add-database-node.mdx index 2cb4d31d60..b9fe604e59 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/add-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx index aee0d3102b..e9118cf383 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/delete-certificate.mdx index f916163c53..a533d68ca2 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx index 2527bf1aff..047f33765b 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index 3042e7dc25..3137e56b18 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index c474bd59a1..14126836c5 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/create-database.mdx index abd4d68c0d..ea75a81467 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-4.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/promote-database-node.mdx index a1b342c55a..14e10ef548 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/restore-backup.mdx index 0a28a9ca56..122865eee3 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/restore-backup.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-databases-state.mdx index 61b9d9a396..fd4c1e4e85 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-4.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/operations/what-are-operations.mdx b/versioned_docs/version-4.2/client-api/operations/what-are-operations.mdx index 7c2ad27db8..9f02c7218e 100644 --- a/versioned_docs/version-4.2/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-4.2/client-api/operations/what-are-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_deleting-csharp.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_deleting-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_deleting-java.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_deleting-java.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_deleting-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_loading-csharp.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_loading-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_loading-java.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_loading-java.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_storing-csharp.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_storing-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_storing-java.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_storing-java.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_storing-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_storing-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/attachments/copying-moving-renaming.mdx b/versioned_docs/version-4.2/client-api/session/attachments/copying-moving-renaming.mdx index 99de0ae4c8..22f992e1d0 100644 --- a/versioned_docs/version-4.2/client-api/session/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-4.2/client-api/session/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/attachments/deleting.mdx b/versioned_docs/version-4.2/client-api/session/attachments/deleting.mdx index 3433931530..9470a16e40 100644 --- a/versioned_docs/version-4.2/client-api/session/attachments/deleting.mdx +++ b/versioned_docs/version-4.2/client-api/session/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/attachments/loading.mdx b/versioned_docs/version-4.2/client-api/session/attachments/loading.mdx index 2acde9fdac..57c19032be 100644 --- a/versioned_docs/version-4.2/client-api/session/attachments/loading.mdx +++ b/versioned_docs/version-4.2/client-api/session/attachments/loading.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/attachments/storing.mdx b/versioned_docs/version-4.2/client-api/session/attachments/storing.mdx index 2861d1ad25..47022f1708 100644 --- a/versioned_docs/version-4.2/client-api/session/attachments/storing.mdx +++ b/versioned_docs/version-4.2/client-api/session/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/attachments/what-are-attachments.mdx b/versioned_docs/version-4.2/client-api/session/attachments/what-are-attachments.mdx index f8d3bea98c..17b91b137b 100644 --- a/versioned_docs/version-4.2/client-api/session/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-4.2/client-api/session/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-tracking-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-tracking-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-disable-tracking-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-disable-tracking-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-tracking.mdx index 81bd1835bb..3735376c95 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingJava from './_how-to-disable-tracking-java.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingJava from './content/_how-to-disable-tracking-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-4.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-4.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-4.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-4.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-4.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-4.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_create-or-modify-java.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_create-or-modify-java.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_delete-csharp.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_delete-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_delete-java.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_delete-java.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_overview-csharp.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_overview-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_overview-java.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_overview-java.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-4.2/client-api/session/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-4.2/client-api/session/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/counters/counters-and-other-features.mdx b/versioned_docs/version-4.2/client-api/session/counters/counters-and-other-features.mdx index bb6ecdf83a..a8bed052da 100644 --- a/versioned_docs/version-4.2/client-api/session/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-4.2/client-api/session/counters/counters-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/counters/create-or-modify.mdx b/versioned_docs/version-4.2/client-api/session/counters/create-or-modify.mdx index 9926c401a6..4fcbd6f430 100644 --- a/versioned_docs/version-4.2/client-api/session/counters/create-or-modify.mdx +++ b/versioned_docs/version-4.2/client-api/session/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/counters/delete.mdx b/versioned_docs/version-4.2/client-api/session/counters/delete.mdx index 57486f37e2..19f0c9e637 100644 --- a/versioned_docs/version-4.2/client-api/session/counters/delete.mdx +++ b/versioned_docs/version-4.2/client-api/session/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/counters/overview.mdx b/versioned_docs/version-4.2/client-api/session/counters/overview.mdx index e3f2e7dc98..520cdd444d 100644 --- a/versioned_docs/version-4.2/client-api/session/counters/overview.mdx +++ b/versioned_docs/version-4.2/client-api/session/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/counters/retrieve-counter-values.mdx b/versioned_docs/version-4.2/client-api/session/counters/retrieve-counter-values.mdx index f876091f0b..d52393ec25 100644 --- a/versioned_docs/version-4.2/client-api/session/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-4.2/client-api/session/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/deleting-entities.mdx b/versioned_docs/version-4.2/client-api/session/deleting-entities.mdx index 7830ac0cba..5d7364f947 100644 --- a/versioned_docs/version-4.2/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-4.2/client-api/session/how-to/check-if-attachment-exists.mdx index a87cd5c6dc..ac371e05a6 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-4.2/client-api/session/how-to/check-if-document-exists.mdx index f65fc256df..100f8f8655 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/check-if-document-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-4.2/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-4.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-4.2/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-4.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-4.2/client-api/session/how-to/defer-operations.mdx index e126593869..dd839bc6af 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-4.2/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-counters.mdx index bb4c0c5293..65488aa1a6 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-counters.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-4.2/client-api/session/how-to/ignore-entity-changes.mdx index ec0fea1629..d46a577949 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-4.2/client-api/session/how-to/perform-operations-lazily.mdx index a58c0c1d16..1e12e4cd05 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyJava from './_perform-operations-lazily-java.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyJava from './content/_perform-operations-lazily-java.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-4.2/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-4.2/client-api/session/how-to/subscribe-to-events.mdx index 8ee4d73d09..7e3b972ad5 100644 --- a/versioned_docs/version-4.2/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-4.2/client-api/session/how-to/subscribe-to-events.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/loading-entities.mdx b/versioned_docs/version-4.2/client-api/session/loading-entities.mdx index 2a39a6fb00..8214ff7506 100644 --- a/versioned_docs/version-4.2/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/opening-a-session.mdx b/versioned_docs/version-4.2/client-api/session/opening-a-session.mdx index 0b2921a7fa..bf2464701a 100644 --- a/versioned_docs/version-4.2/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-4.2/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 90b70a1b8f..0000000000 --- a/versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# How to Filter by Non-Existing Field - - -* There are situations where over time new fields are added to documents. - You may need to create a list of all of the documents that don't have these fields. - * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) - to add the missing fields. - -* To find documents with a missing field you can either: - * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) - * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) - - - -## Query a Static Index - -You can search for documents with missing fields by using a static index if it indexes the field which is -suspected to be missing in some of the documents. - -The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. - -* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, - query an index that indexes the fields `Freight` and `Id`. -* If your static index does not contain the desired field, either - * Modify your index definition to index the specific field. (This will trigger re-indexing.) - * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). - -### Example: Query a Static Index - -In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. - -#### First we need an index that includes `Freight` and a field that exists in every document - -We index the missing field `Freight` and the field `Id`, which exists in every document. -This way, the index includes all of the documents in the collection, -including those that are missing the specified field. - - - -{`// Create or modify a static index called Orders_ByFreight -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public Orders_ByFreight() - \{ - // Specify collection name - Map = orders => from doc in orders - select new - \{ - // Field that is missing in some documents - doc.Freight, - // Field that exists in all documents - doc.Id - \}; - \} -\} -`} - - - -#### Then we query the index to find documents where the field does not exist - -SAMPLE QUERY: - -Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. - - - - -{`List results = session - .Advanced - // Query the static index - .DocumentQuery() - // Verify that the index is not stale (optional) - .WaitForNonStaleResults(TimeSpan.MaxValue) - // Negate the next method - .Not - // Specify the field that is suspected to be missing - .WhereExists(x => x.Freight) - .ToList(); - // \`results\` will contain the list of incomplete documents. -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - -LINQ SYNTAX: - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **TIndexCreator** | string | The name of the index that you want to use. | -| **missingFieldName**| string | The field that is missing in some of the documents. | - - - - -## Query the Collection to Create an Auto-Index - -Another option is to query the collection for the missing field. -This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. - -See the example and query syntax descriptions below: - -### Example: A query that creates an Auto-Index - -The following query will create an auto-index on the "Freight" field -that is missing in some documents in the Orders collection. -The query result will contain all documents that do not have this field. - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("Freight") - .ToList(); -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - -#### LINQ Query Syntax - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **missingFieldName** | string | The field that is missing in some of the documents. | - - - - - -## Use Studio to filter by non-existing field - -You can also use Studio to find missing fields with an RQL query such as: - -``` -from "Orders" -where exists("Company") and not exists("Freight") -``` - -In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. -Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), -we must first call a field that exists in every document in the collection -and then the field that does not exist in some of them. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu items. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created for this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not have the specified field. - (The field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx deleted file mode 100644 index 17f9666668..0000000000 --- a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx +++ /dev/null @@ -1,549 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of -spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, -and `OrderByDistanceDescending`. - -* In this page: - * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) - * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) - * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - - -## Spatial - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | - -### DynamicSpatialFieldFactory - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | -| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in index | -| **fieldName** | `string` | Path to spatial field in index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - -### Example II - -This example demonstrates rounding. The query sorts the results by distance from -the specified point, but rounds the distance up to the nearest 100 km interval. -All results within the same interval are sorted alphabetically by the field `Name`. - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = session - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToList(); -`} - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToListAsync(); -`} - - - - -{`from Houses as h -order by spatial.distance( - spatial.point(h.Latitude, h.Longitude), - spatial.point(32.1234, 23.4321), - 100), h.Name -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx deleted file mode 100644 index 9c5caf9969..0000000000 --- a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..68ea5e01e7 --- /dev/null +++ b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# How to Filter by Non-Existing Field + + +* There are situations where over time new fields are added to documents. + You may need to create a list of all of the documents that don't have these fields. + * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) + to add the missing fields. + +* To find documents with a missing field you can either: + * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) + * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) + + + +## Query a Static Index + +You can search for documents with missing fields by using a static index if it indexes the field which is +suspected to be missing in some of the documents. + +The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. + +* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, + query an index that indexes the fields `Freight` and `Id`. +* If your static index does not contain the desired field, either + * Modify your index definition to index the specific field. (This will trigger re-indexing.) + * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). + +### Example: Query a Static Index + +In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. + +#### First we need an index that includes `Freight` and a field that exists in every document + +We index the missing field `Freight` and the field `Id`, which exists in every document. +This way, the index includes all of the documents in the collection, +including those that are missing the specified field. + + + +{`// Create or modify a static index called Orders_ByFreight +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public Orders_ByFreight() + \{ + // Specify collection name + Map = orders => from doc in orders + select new + \{ + // Field that is missing in some documents + doc.Freight, + // Field that exists in all documents + doc.Id + \}; + \} +\} +`} + + + +#### Then we query the index to find documents where the field does not exist + +SAMPLE QUERY: + +Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. + + + + +{`List results = session + .Advanced + // Query the static index + .DocumentQuery() + // Verify that the index is not stale (optional) + .WaitForNonStaleResults(TimeSpan.MaxValue) + // Negate the next method + .Not + // Specify the field that is suspected to be missing + .WhereExists(x => x.Freight) + .ToList(); + // \`results\` will contain the list of incomplete documents. +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + +LINQ SYNTAX: + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **TIndexCreator** | string | The name of the index that you want to use. | +| **missingFieldName**| string | The field that is missing in some of the documents. | + + + + +## Query the Collection to Create an Auto-Index + +Another option is to query the collection for the missing field. +This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. + +See the example and query syntax descriptions below: + +### Example: A query that creates an Auto-Index + +The following query will create an auto-index on the "Freight" field +that is missing in some documents in the Orders collection. +The query result will contain all documents that do not have this field. + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("Freight") + .ToList(); +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + +#### LINQ Query Syntax + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **missingFieldName** | string | The field that is missing in some of the documents. | + + + + + +## Use Studio to filter by non-existing field + +You can also use Studio to find missing fields with an RQL query such as: + +``` +from "Orders" +where exists("Company") and not exists("Freight") +``` + +In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. +Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), +we must first call a field that exists in every document in the collection +and then the field that does not exist in some of them. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu items. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created for this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not have the specified field. + (The field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-proximity-search-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-proximity-search-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx new file mode 100644 index 0000000000..f76839a4dc --- /dev/null +++ b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx @@ -0,0 +1,549 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of +spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, +and `OrderByDistanceDescending`. + +* In this page: + * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) + * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) + * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + + +## Spatial + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | + +### DynamicSpatialFieldFactory + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | +| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in index | +| **fieldName** | `string` | Path to spatial field in index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + +### Example II + +This example demonstrates rounding. The query sorts the results by distance from +the specified point, but rounds the distance up to the nearest 100 km interval. +All results within the same interval are sorted alphabetically by the field `Name`. + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = session + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToList(); +`} + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToListAsync(); +`} + + + + +{`from Houses as h +order by spatial.distance( + spatial.point(h.Latitude, h.Longitude), + spatial.point(32.1234, 23.4321), + 100), h.Name +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx new file mode 100644 index 0000000000..2396725492 --- /dev/null +++ b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-fuzzy-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-fuzzy-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-regex-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index a64e783cc2..0000000000 --- a/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery Timings(out QueryTimings timings); -`} - - - -## Example - - - - -{`var resultWithTimings = session.Advanced.DocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToList(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToListAsync(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index a85ad6f470..0000000000 --- a/versioned_docs/version-4.2/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..b777106c96 --- /dev/null +++ b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,57 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery Timings(out QueryTimings timings); +`} + + + +## Example + + + + +{`var resultWithTimings = session.Advanced.DocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToList(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToListAsync(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..99f3fa91d6 --- /dev/null +++ b/versioned_docs/version-4.2/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/include-explanations.mdx index ec808ee6a9..4df35b7773 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/debugging/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-4.2/client-api/session/querying/debugging/query-timings.mdx index 945f73958f..7986688800 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/debugging/query-timings.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-4.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-4.2/client-api/session/querying/document-query/what-is-document-query.mdx index cef08c1c05..798546d402 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-customize-query.mdx index 2e9f4cd49b..d8110e41f3 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-field.mdx index f0ff8185c2..285ee08861 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 38b64f0c4f..d194cb8bcf 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-get-query-statistics.mdx index 83a9c90774..433e7bbfad 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx index e715a770b3..1b6695fbca 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-proximity-search.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-proximity-search.mdx index ddaa663299..622e2335b3 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-proximity-search.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-proximity-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProximitySearchCsharp from './_how-to-perform-proximity-search-csharp.mdx'; -import HowToPerformProximitySearchJava from './_how-to-perform-proximity-search-java.mdx'; +import HowToPerformProximitySearchCsharp from './content/_how-to-perform-proximity-search-csharp.mdx'; +import HowToPerformProximitySearchJava from './content/_how-to-perform-proximity-search-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-queries-lazily.mdx index e32d80e161..81bbc4fa19 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-project-query-results.mdx index 4064387648..9c7d07ff5c 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-query-a-spatial-index.mdx index a61668f911..2a328088f5 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-query-with-exact-match.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-query-with-exact-match.mdx index 29dadbe6eb..c6befd9e24 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-query-with-exact-match.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-query-with-exact-match.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryWithExactMatchCsharp from './_how-to-query-with-exact-match-csharp.mdx'; -import HowToQueryWithExactMatchJava from './_how-to-query-with-exact-match-java.mdx'; -import HowToQueryWithExactMatchNodejs from './_how-to-query-with-exact-match-nodejs.mdx'; +import HowToQueryWithExactMatchCsharp from './content/_how-to-query-with-exact-match-csharp.mdx'; +import HowToQueryWithExactMatchJava from './content/_how-to-query-with-exact-match-java.mdx'; +import HowToQueryWithExactMatchNodejs from './content/_how-to-query-with-exact-match-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-query.mdx index 5338135aad..65f0860b27 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-stream-query-results.mdx index 75d86a60b2..69bde8d43d 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-fuzzy.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-fuzzy.mdx index 1b18017dcb..9d2276243c 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-fuzzy.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-fuzzy.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseFuzzyCsharp from './_how-to-use-fuzzy-csharp.mdx'; -import HowToUseFuzzyJava from './_how-to-use-fuzzy-java.mdx'; +import HowToUseFuzzyCsharp from './content/_how-to-use-fuzzy-csharp.mdx'; +import HowToUseFuzzyJava from './content/_how-to-use-fuzzy-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-highlighting.mdx index 93ef8a0c20..a03a38aeea 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-regex.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-regex.mdx index d46f82cab1..e0e9f41896 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-regex.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseRegexCsharp from './_how-to-use-regex-csharp.mdx'; -import HowToUseRegexJava from './_how-to-use-regex-java.mdx'; -import HowToUseRegexNodejs from './_how-to-use-regex-nodejs.mdx'; +import HowToUseRegexCsharp from './content/_how-to-use-regex-csharp.mdx'; +import HowToUseRegexJava from './content/_how-to-use-regex-java.mdx'; +import HowToUseRegexNodejs from './content/_how-to-use-regex-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-search.mdx index 8e128dfebb..eab93a36f4 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-use-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-4.2/client-api/session/querying/how-to-work-with-suggestions.mdx index dfc2413f17..c15846553c 100644 --- a/versioned_docs/version-4.2/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-4.2/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_counter-revisions-csharp.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_counter-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_counter-revisions-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_counter-revisions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_counter-revisions-java.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_counter-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_counter-revisions-java.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_counter-revisions-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-4.2/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-4.2/client-api/session/revisions/counter-revisions.mdx b/versioned_docs/version-4.2/client-api/session/revisions/counter-revisions.mdx index 2685ffaefe..096cb444a7 100644 --- a/versioned_docs/version-4.2/client-api/session/revisions/counter-revisions.mdx +++ b/versioned_docs/version-4.2/client-api/session/revisions/counter-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterRevisionsCsharp from './_counter-revisions-csharp.mdx'; -import CounterRevisionsJava from './_counter-revisions-java.mdx'; +import CounterRevisionsCsharp from './content/_counter-revisions-csharp.mdx'; +import CounterRevisionsJava from './content/_counter-revisions-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/revisions/loading.mdx b/versioned_docs/version-4.2/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-4.2/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-4.2/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-4.2/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-4.2/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-4.2/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/saving-changes.mdx b/versioned_docs/version-4.2/client-api/session/saving-changes.mdx index b2f757ca4c..190869532f 100644 --- a/versioned_docs/version-4.2/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-4.2/client-api/session/saving-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/storing-entities.mdx b/versioned_docs/version-4.2/client-api/session/storing-entities.mdx index 09787c1800..dafb1abe29 100644 --- a/versioned_docs/version-4.2/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/updating-entities.mdx b/versioned_docs/version-4.2/client-api/session/updating-entities.mdx index c7a719d596..58a56a1004 100644 --- a/versioned_docs/version-4.2/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-4.2/client-api/session/updating-entities.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-4.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx index 1eb9ad91cf..c17516971d 100644 --- a/versioned_docs/version-4.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-4.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-4.2/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-4.2/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-4.2/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-4.2/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/setting-up-default-database.mdx b/versioned_docs/version-4.2/client-api/setting-up-default-database.mdx index 75fc4c2450..b217f301b3 100644 --- a/versioned_docs/version-4.2/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-4.2/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-4.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-4.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-4.2/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-4.2/client-api/smuggler/what-is-smuggler.mdx index f1af37fb68..da1d8be3d1 100644 --- a/versioned_docs/version-4.2/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-4.2/client-api/smuggler/what-is-smuggler.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; diff --git a/versioned_docs/version-4.2/client-api/what-is-a-document-store.mdx b/versioned_docs/version-4.2/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-4.2/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-4.2/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-4.2/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-4.2/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-4.2/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_index-query-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_index-query-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_query-result-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_query-result-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/_stream-result-csharp.mdx b/versioned_docs/version-4.2/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-4.2/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-4.2/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-4.2/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-4.2/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/counters-batch-command-data.mdx b/versioned_docs/version-4.2/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-4.2/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/delete-command-data.mdx b/versioned_docs/version-4.2/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-4.2/glossary/delete-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-4.2/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-4.2/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/index-query.mdx b/versioned_docs/version-4.2/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-4.2/glossary/index-query.mdx +++ b/versioned_docs/version-4.2/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/move-attachment-command-data.mdx b/versioned_docs/version-4.2/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-4.2/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/patch-command-data.mdx b/versioned_docs/version-4.2/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-4.2/glossary/patch-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/put-command-data.mdx b/versioned_docs/version-4.2/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-4.2/glossary/put-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-4.2/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-4.2/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-4.2/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/query-result.mdx b/versioned_docs/version-4.2/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-4.2/glossary/query-result.mdx +++ b/versioned_docs/version-4.2/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/stream-query-statistics.mdx b/versioned_docs/version-4.2/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-4.2/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-4.2/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-4.2/glossary/stream-result.mdx b/versioned_docs/version-4.2/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-4.2/glossary/stream-result.mdx +++ b/versioned_docs/version-4.2/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-4.2/indexes/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/_fanout-indexes-csharp.mdx deleted file mode 100644 index 94f6065246..0000000000 --- a/versioned_docs/version-4.2/indexes/_fanout-indexes-csharp.mdx +++ /dev/null @@ -1,171 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public class Orders_ByProduct : AbstractIndexCreationTask -{ - public Orders_ByProduct() - { - Map = orders => from order in orders - from orderLine in order.Lines - select new - { - orderLine.Product, - orderLine.ProductName - }; - } -} -`} - - - - -{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByProduct() - { - Maps = new HashSet - { - @"map('Orders', function (order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - ProductName: l.ProductName - }) - }); - return res; - })", - }; - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public class Product_Sales : AbstractIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - public int Count { get; set; } - public decimal Total; - } - - public Product_Sales() - { - Map = orders => from order in orders - from line in order.Lines - select new Result - { - Product = line.Product, - Count = 1, - Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) - }; - - Reduce = results => from result in results - group result by result.Product - into g - select new - { - Product = g.Key, - Count = g.Sum(x => x.Count), - Total = g.Sum(x => x.Total) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.2/indexes/_fanout-indexes-java.mdx b/versioned_docs/version-4.2/indexes/_fanout-indexes-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-4.2/indexes/_fanout-indexes-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-4.2/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-4.2/indexes/boosting.mdx b/versioned_docs/version-4.2/indexes/boosting.mdx index 63937b73b3..4e299192ad 100644 --- a/versioned_docs/version-4.2/indexes/boosting.mdx +++ b/versioned_docs/version-4.2/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/_boosting-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_boosting-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_boosting-java.mdx b/versioned_docs/version-4.2/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_boosting-java.mdx rename to versioned_docs/version-4.2/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_boosting-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_extending-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/content/_fanout-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_fanout-indexes-csharp.mdx new file mode 100644 index 0000000000..bb8d3382d9 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/content/_fanout-indexes-csharp.mdx @@ -0,0 +1,171 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public class Orders_ByProduct : AbstractIndexCreationTask +{ + public Orders_ByProduct() + { + Map = orders => from order in orders + from orderLine in order.Lines + select new + { + orderLine.Product, + orderLine.ProductName + }; + } +} +`} + + + + +{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByProduct() + { + Maps = new HashSet + { + @"map('Orders', function (order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + ProductName: l.ProductName + }) + }); + return res; + })", + }; + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public class Product_Sales : AbstractIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + public int Count { get; set; } + public decimal Total; + } + + public Product_Sales() + { + Map = orders => from order in orders + from line in order.Lines + select new Result + { + Product = line.Product, + Count = 1, + Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) + }; + + Reduce = results => from result in results + group result by result.Product + into g + select new + { + Product = g.Key, + Count = g.Sum(x => x.Count), + Total = g.Sum(x => x.Total) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.2/indexes/content/_fanout-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_fanout-indexes-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/content/_fanout-indexes-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-4.2/indexes/_indexing-attachments-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-attachments-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-attachments-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-attachments-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-attachments-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-attachments-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-attachments-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-basics-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-counters-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-counters-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-counters-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-counters-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-counters-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-counters-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-counters-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-hierarchical-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-hierarchical-data-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-hierarchical-data-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-4.2/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-related-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-related-documents-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-related-documents-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-4.2/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-4.2/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-4.2/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-4.2/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_stale-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-4.2/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-4.2/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-analyzers-java.mdx b/versioned_docs/version-4.2/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-4.2/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_using-dynamic-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-dynamic-fields-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_using-dynamic-fields-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-4.2/indexes/content/_using-dynamic-fields-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-dynamic-fields-java.mdx rename to versioned_docs/version-4.2/indexes/content/_using-dynamic-fields-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-4.2/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-4.2/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-4.2/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-4.2/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-4.2/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-4.2/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-4.2/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-4.2/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-4.2/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-4.2/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-4.2/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-4.2/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/creating-and-deploying.mdx b/versioned_docs/version-4.2/indexes/creating-and-deploying.mdx index ad82e6dc99..e0eebf6640 100644 --- a/versioned_docs/version-4.2/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-4.2/indexes/creating-and-deploying.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; diff --git a/versioned_docs/version-4.2/indexes/extending-indexes.mdx b/versioned_docs/version-4.2/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-4.2/indexes/extending-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/fanout-indexes.mdx b/versioned_docs/version-4.2/indexes/fanout-indexes.mdx index c07252a661..c76c4ee85f 100644 --- a/versioned_docs/version-4.2/indexes/fanout-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/fanout-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FanoutIndexesCsharp from './_fanout-indexes-csharp.mdx'; -import FanoutIndexesJava from './_fanout-indexes-java.mdx'; +import FanoutIndexesCsharp from './content/_fanout-indexes-csharp.mdx'; +import FanoutIndexesJava from './content/_fanout-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-attachments.mdx b/versioned_docs/version-4.2/indexes/indexing-attachments.mdx index 97d164dc49..5f230632f4 100644 --- a/versioned_docs/version-4.2/indexes/indexing-attachments.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-attachments.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingAttachmentsCsharp from './_indexing-attachments-csharp.mdx'; -import IndexingAttachmentsJava from './_indexing-attachments-java.mdx'; +import IndexingAttachmentsCsharp from './content/_indexing-attachments-csharp.mdx'; +import IndexingAttachmentsJava from './content/_indexing-attachments-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-basics.mdx b/versioned_docs/version-4.2/indexes/indexing-basics.mdx index 72b153a25f..15560b37fc 100644 --- a/versioned_docs/version-4.2/indexes/indexing-basics.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-counters.mdx b/versioned_docs/version-4.2/indexes/indexing-counters.mdx index 6996054ad7..f73233fbfd 100644 --- a/versioned_docs/version-4.2/indexes/indexing-counters.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCountersCsharp from './_indexing-counters-csharp.mdx'; -import IndexingCountersJava from './_indexing-counters-java.mdx'; +import IndexingCountersCsharp from './content/_indexing-counters-csharp.mdx'; +import IndexingCountersJava from './content/_indexing-counters-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-4.2/indexes/indexing-hierarchical-data.mdx index ebe167fdaa..b0481950bf 100644 --- a/versioned_docs/version-4.2/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-hierarchical-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-4.2/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-4.2/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-4.2/indexes/indexing-polymorphic-data.mdx index bddb362a3a..4c08de81be 100644 --- a/versioned_docs/version-4.2/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-related-documents.mdx b/versioned_docs/version-4.2/indexes/indexing-related-documents.mdx index 528f4459ea..b8cec71b26 100644 --- a/versioned_docs/version-4.2/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-related-documents.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/indexing-spatial-data.mdx b/versioned_docs/version-4.2/indexes/indexing-spatial-data.mdx index 7f0511363d..caca7442e3 100644 --- a/versioned_docs/version-4.2/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-4.2/indexes/indexing-spatial-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/javascript-indexes.mdx b/versioned_docs/version-4.2/indexes/javascript-indexes.mdx index 7317155649..44909a2261 100644 --- a/versioned_docs/version-4.2/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/map-indexes.mdx b/versioned_docs/version-4.2/indexes/map-indexes.mdx index e65cd6bd51..d0ca5316e0 100644 --- a/versioned_docs/version-4.2/indexes/map-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/map-indexes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; diff --git a/versioned_docs/version-4.2/indexes/map-reduce-indexes.mdx b/versioned_docs/version-4.2/indexes/map-reduce-indexes.mdx index 67f28f3ee9..b0226e7feb 100644 --- a/versioned_docs/version-4.2/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/map-reduce-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/multi-map-indexes.mdx b/versioned_docs/version-4.2/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-4.2/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 01b66b3e5d..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,349 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **Cost** field, return the count of the following ranges: - - * Cost < 200.0 - * 200.0 <= Cost < 400.0 - * 400.0 <= Cost < 600.0 - * 600.0 <= Cost < 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels < 7.0 - * 7.0 <= Megapixels < 10.0 - * Megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "Manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "Cost", - "Values": [ - \{ - "Count": 6, - "Range": "Cost <= 200" - \}, - \{ - "Count": 2, - "Range": "Cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "Cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "Cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "Cost >= 800" - \} - ] - \}, - \{ - "Name": "Megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "Megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "Megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "Megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "Megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.2/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-4.2/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 54c908d478..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.2/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 690e4df1df..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,312 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`export class Camera \{ - constructor(manufacturer, model, \{ - dateOfListing, - cost, - zoom, - megapixels, - imageStabilizer - \}) \{ - this.manufacturer = manufacturer; - this.model = model; - this.dateOfListing = dateOfListing; - this.cost = cost; - this.zoom = zoom; - this.megapixels = megapixels; - this.imageStabilizer = imageStabilizer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = \`from camera in docs.Cameras select new \{ - camera.manufacturer, - camera.model, - camera.cost, - camera.dateOfListing, - camera.megapixels - \}\`; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`const facetSetup = new FacetSetup(); -facetSetup.facets = facets; -facetSetup.rangeFacets = rangeFacets; - -await session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`const facetResults = await session - .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`const facet1 = new Facet(); -facet1.fieldName = "manufacturer"; - -const facet2 = new RangeFacet(); -facet2.ranges = [ - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -]; - -const facet3 = new RangeFacet(); -facet3.ranges = [ - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -]; - -const facets = [ facet1 ]; -const rangeFacets = [ facet2, facet3 ]; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-4.2/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ecb4312302..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.2/indexes/querying/_paging-java.mdx b/versioned_docs/version-4.2/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-4.2/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index e52c0cff7a..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a Fanout index. - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-4.2/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/_spatial-csharp.mdx deleted file mode 100644 index b8e29cae09..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_spatial-csharp.mdx +++ /dev/null @@ -1,165 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `RelatesToShape` - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .Query() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`public class Events_ByCoordinates : AbstractIndexCreationTask -{ - public Events_ByCoordinates() - { - Map = events => from e in events - select new - { - Coordinates = CreateSpatialField(e.Latitude, e.Longitude) - }; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(Coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.2/indexes/querying/_spatial-java.mdx b/versioned_docs/version-4.2/indexes/querying/_spatial-java.mdx deleted file mode 100644 index 052325a8dc..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.2/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/_spatial-nodejs.mdx deleted file mode 100644 index 77542032c5..0000000000 --- a/versioned_docs/version-4.2/indexes/querying/_spatial-nodejs.mdx +++ /dev/null @@ -1,122 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape()` - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - "Within" - )) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`const results = await session - .query({ indexName: "Events/ByCoordinates" }) - .spatial("coordinates", - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`class Events_ByCoordinates extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Events.Select(e => new { - Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) - })\`; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-4.2/indexes/querying/basics.mdx b/versioned_docs/version-4.2/indexes/querying/basics.mdx index f1cbf38302..23f7507680 100644 --- a/versioned_docs/version-4.2/indexes/querying/basics.mdx +++ b/versioned_docs/version-4.2/indexes/querying/basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; -import BasicsNodejs from './_basics-nodejs.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; +import BasicsNodejs from './content/_basics-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/boosting.mdx b/versioned_docs/version-4.2/indexes/querying/boosting.mdx index 97dc2a028f..35a0a0b712 100644 --- a/versioned_docs/version-4.2/indexes/querying/boosting.mdx +++ b/versioned_docs/version-4.2/indexes/querying/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_basics-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_basics-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_basics-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_basics-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_basics-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_boosting-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_boosting-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_boosting-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_boosting-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_boosting-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_boosting-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_boosting-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_distinct-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..62e55bba88 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,349 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **Cost** field, return the count of the following ranges: + + * Cost < 200.0 + * 200.0 <= Cost < 400.0 + * 400.0 <= Cost < 600.0 + * 600.0 <= Cost < 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels < 7.0 + * 7.0 <= Megapixels < 10.0 + * Megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(Manufacturer), facet(Cost <= 200, Cost between 200 and 400, Cost between 400 and 600, Cost between 600 and 800, Cost >= 800), facet(Megapixels <= 3, Megapixels between 3 and 7, Megapixels between 7 and 10, Megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "Manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "Cost", + "Values": [ + \{ + "Count": 6, + "Range": "Cost <= 200" + \}, + \{ + "Count": 2, + "Range": "Cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "Cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "Cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "Cost >= 800" + \} + ] + \}, + \{ + "Name": "Megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "Megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "Megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "Megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "Megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..2dca93bfaf --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..2b4d199a3d --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,312 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`export class Camera \{ + constructor(manufacturer, model, \{ + dateOfListing, + cost, + zoom, + megapixels, + imageStabilizer + \}) \{ + this.manufacturer = manufacturer; + this.model = model; + this.dateOfListing = dateOfListing; + this.cost = cost; + this.zoom = zoom; + this.megapixels = megapixels; + this.imageStabilizer = imageStabilizer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = \`from camera in docs.Cameras select new \{ + camera.manufacturer, + camera.model, + camera.cost, + camera.dateOfListing, + camera.megapixels + \}\`; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`const facetSetup = new FacetSetup(); +facetSetup.facets = facets; +facetSetup.rangeFacets = rangeFacets; + +await session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`const facetResults = await session + .query({ indexName: "Cameras/ByManufacturerModelCostDateOfListingAndMegapixels" }) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`const facet1 = new Facet(); +facet1.fieldName = "manufacturer"; + +const facet2 = new RangeFacet(); +facet2.ranges = [ + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +]; + +const facet3 = new RangeFacet(); +facet3.ranges = [ + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +]; + +const facets = [ facet1 ]; +const rangeFacets = [ facet2, facet3 ]; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults()` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy()` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-4.2/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_filtering-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_intersection-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..967fb68620 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2cc2e022a --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a Fanout index. + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-4.2/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_projections-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_projections-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_sorting-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/content/_spatial-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_spatial-csharp.mdx new file mode 100644 index 0000000000..1062993808 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_spatial-csharp.mdx @@ -0,0 +1,165 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `RelatesToShape` + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .Query() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`public class Events_ByCoordinates : AbstractIndexCreationTask +{ + public Events_ByCoordinates() + { + Map = events => from e in events + select new + { + Coordinates = CreateSpatialField(e.Latitude, e.Longitude) + }; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(Coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..9c11a03099 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.2/indexes/querying/content/_spatial-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_spatial-nodejs.mdx new file mode 100644 index 0000000000..9e318daef2 --- /dev/null +++ b/versioned_docs/version-4.2/indexes/querying/content/_spatial-nodejs.mdx @@ -0,0 +1,122 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape()` + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + "Within" + )) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`const results = await session + .query({ indexName: "Events/ByCoordinates" }) + .spatial("coordinates", + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`class Events_ByCoordinates extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Events.Select(e => new { + Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) + })\`; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-4.2/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-4.2/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-4.2/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-4.2/indexes/querying/content/_suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-4.2/indexes/querying/_suggestions-nodejs.mdx rename to versioned_docs/version-4.2/indexes/querying/content/_suggestions-nodejs.mdx diff --git a/versioned_docs/version-4.2/indexes/querying/distinct.mdx b/versioned_docs/version-4.2/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-4.2/indexes/querying/distinct.mdx +++ b/versioned_docs/version-4.2/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/faceted-search.mdx b/versioned_docs/version-4.2/indexes/querying/faceted-search.mdx index 642a2a77a5..b9e984e8b0 100644 --- a/versioned_docs/version-4.2/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-4.2/indexes/querying/faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/filtering.mdx b/versioned_docs/version-4.2/indexes/querying/filtering.mdx index c1c3bf3139..ba11c389e5 100644 --- a/versioned_docs/version-4.2/indexes/querying/filtering.mdx +++ b/versioned_docs/version-4.2/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/highlighting.mdx b/versioned_docs/version-4.2/indexes/querying/highlighting.mdx index caddfb8b7c..98d011b0fb 100644 --- a/versioned_docs/version-4.2/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-4.2/indexes/querying/highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/intersection.mdx b/versioned_docs/version-4.2/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-4.2/indexes/querying/intersection.mdx +++ b/versioned_docs/version-4.2/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/morelikethis.mdx b/versioned_docs/version-4.2/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-4.2/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-4.2/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/paging.mdx b/versioned_docs/version-4.2/indexes/querying/paging.mdx index 4a4f877127..1375a3d67e 100644 --- a/versioned_docs/version-4.2/indexes/querying/paging.mdx +++ b/versioned_docs/version-4.2/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/projections.mdx b/versioned_docs/version-4.2/indexes/querying/projections.mdx index f358bb4489..84724cf411 100644 --- a/versioned_docs/version-4.2/indexes/querying/projections.mdx +++ b/versioned_docs/version-4.2/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-4.2/indexes/querying/query-vs-document-query.mdx index b766203269..8d99869330 100644 --- a/versioned_docs/version-4.2/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-4.2/indexes/querying/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/searching.mdx b/versioned_docs/version-4.2/indexes/querying/searching.mdx index 2f747d4661..fb4145a63d 100644 --- a/versioned_docs/version-4.2/indexes/querying/searching.mdx +++ b/versioned_docs/version-4.2/indexes/querying/searching.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/sorting.mdx b/versioned_docs/version-4.2/indexes/querying/sorting.mdx index a230093906..fc72ce4f44 100644 --- a/versioned_docs/version-4.2/indexes/querying/sorting.mdx +++ b/versioned_docs/version-4.2/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/spatial.mdx b/versioned_docs/version-4.2/indexes/querying/spatial.mdx index 1e4e0092b9..5df771eb7a 100644 --- a/versioned_docs/version-4.2/indexes/querying/spatial.mdx +++ b/versioned_docs/version-4.2/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/querying/suggestions.mdx b/versioned_docs/version-4.2/indexes/querying/suggestions.mdx index 8e46c2ed39..d5209e47da 100644 --- a/versioned_docs/version-4.2/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-4.2/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/sorting-and-collation.mdx b/versioned_docs/version-4.2/indexes/sorting-and-collation.mdx index c55cbb45c0..f3c27ca9c0 100644 --- a/versioned_docs/version-4.2/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-4.2/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/stale-indexes.mdx b/versioned_docs/version-4.2/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-4.2/indexes/stale-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/storing-data-in-index.mdx b/versioned_docs/version-4.2/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-4.2/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-4.2/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/using-analyzers.mdx b/versioned_docs/version-4.2/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-4.2/indexes/using-analyzers.mdx +++ b/versioned_docs/version-4.2/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/using-dynamic-fields.mdx b/versioned_docs/version-4.2/indexes/using-dynamic-fields.mdx index b35ee6b88e..b6d6b98cf2 100644 --- a/versioned_docs/version-4.2/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-4.2/indexes/using-dynamic-fields.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; diff --git a/versioned_docs/version-4.2/indexes/using-term-vectors.mdx b/versioned_docs/version-4.2/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-4.2/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-4.2/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/indexes/what-are-indexes.mdx b/versioned_docs/version-4.2/indexes/what-are-indexes.mdx index baeb219b47..613babe12e 100644 --- a/versioned_docs/version-4.2/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-4.2/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-4.2/server/_embedded-csharp.mdx b/versioned_docs/version-4.2/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/server/_embedded-csharp.mdx rename to versioned_docs/version-4.2/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-4.2/server/_embedded-java.mdx b/versioned_docs/version-4.2/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-4.2/server/_embedded-java.mdx rename to versioned_docs/version-4.2/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-4.2/server/embedded.mdx b/versioned_docs/version-4.2/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-4.2/server/embedded.mdx +++ b/versioned_docs/version-4.2/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-4.2/start/_test-driver-csharp.mdx b/versioned_docs/version-4.2/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-4.2/start/_test-driver-csharp.mdx rename to versioned_docs/version-4.2/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-4.2/start/_test-driver-java.mdx b/versioned_docs/version-4.2/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-4.2/start/_test-driver-java.mdx rename to versioned_docs/version-4.2/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-4.2/start/test-driver.mdx b/versioned_docs/version-4.2/start/test-driver.mdx index caaf54ab4c..76d2299c77 100644 --- a/versioned_docs/version-4.2/start/test-driver.mdx +++ b/versioned_docs/version-4.2/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-5.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-5.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-5.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-5.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-5.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-5.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 9b8b55bb6a..dccbc4d7f4 100644 --- a/versioned_docs/version-5.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-5.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-5.0/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-5.0/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-5.0/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-5.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-5.0/client-api/changes/what-is-changes-api.mdx index 111608118f..c761eaa47b 100644 --- a/versioned_docs/version-5.0/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-5.0/client-api/changes/what-is-changes-api.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-5.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-5.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-5.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-5.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-5.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-5.0/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-5.0/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-5.0/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-5.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 5067204d77..d6621b1518 100644 --- a/versioned_docs/version-5.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-5.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-5.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-5.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-5.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-5.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-5.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 3fbea43e2e..eaccf2717d 100644 --- a/versioned_docs/version-5.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-5.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-5.0/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/delete.mdx b/versioned_docs/version-5.0/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-5.0/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-5.0/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/commands/documents/get.mdx b/versioned_docs/version-5.0/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-5.0/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-5.0/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-5.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-5.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-5.0/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-5.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-5.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-5.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-5.0/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/commands/documents/put.mdx b/versioned_docs/version-5.0/client-api/commands/documents/put.mdx index bf35d76f41..0b47252188 100644 --- a/versioned_docs/version-5.0/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-5.0/client-api/commands/documents/put.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-java.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-java.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-java.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-nodejs.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_load-balance-and-failover-nodejs.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_querying-java.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-5.0/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-5.0/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/conventions.mdx b/versioned_docs/version-5.0/client-api/configuration/conventions.mdx index 69915fbd4d..5882c3f020 100644 --- a/versioned_docs/version-5.0/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/conventions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-5.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-5.0/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/load-balance-and-failover.mdx b/versioned_docs/version-5.0/client-api/configuration/load-balance-and-failover.mdx index 677cdab7a6..39c9ec118b 100644 --- a/versioned_docs/version-5.0/client-api/configuration/load-balance-and-failover.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/load-balance-and-failover.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceAndFailoverCsharp from './_load-balance-and-failover-csharp.mdx'; -import LoadBalanceAndFailoverJava from './_load-balance-and-failover-java.mdx'; -import LoadBalanceAndFailoverNodejs from './_load-balance-and-failover-nodejs.mdx'; +import LoadBalanceAndFailoverCsharp from './content/_load-balance-and-failover-csharp.mdx'; +import LoadBalanceAndFailoverJava from './content/_load-balance-and-failover-java.mdx'; +import LoadBalanceAndFailoverNodejs from './content/_load-balance-and-failover-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/querying.mdx b/versioned_docs/version-5.0/client-api/configuration/querying.mdx index c758060e9b..f5bb516607 100644 --- a/versioned_docs/version-5.0/client-api/configuration/querying.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/configuration/serialization.mdx b/versioned_docs/version-5.0/client-api/configuration/serialization.mdx index 7b97467d9e..f531b1b2d0 100644 --- a/versioned_docs/version-5.0/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-5.0/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-5.0/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-5.0/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-5.0/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-5.0/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-5.0/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-5.0/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-5.0/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-5.0/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-5.0/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/creating-document-store.mdx b/versioned_docs/version-5.0/client-api/creating-document-store.mdx index c3703c0c2c..5132778fb7 100644 --- a/versioned_docs/version-5.0/client-api/creating-document-store.mdx +++ b/versioned_docs/version-5.0/client-api/creating-document-store.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index 545845e219..b9549d42f0 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d296754727..46beae2231 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 00e96e6291..09a0baf74b 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/api-overview.mdx index 460655150d..e05c87edf4 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-5.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/examples.mdx index ca8c2f97c2..d5c631951d 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/examples.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-5.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-5.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-5.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-5.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-5.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-5.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-5.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-5.0/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-5.0/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-5.0/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-5.0/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-5.0/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-5.0/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-5.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-5.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-5.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-5.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-5.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-5.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-5.0/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-5.0/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-5.0/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-5.0/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-5.0/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-5.0/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-5.0/client-api/how-to/handle-document-relationships.mdx index b9011b331e..1358702054 100644 --- a/versioned_docs/version-5.0/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-5.0/client-api/how-to/handle-document-relationships.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-5.0/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-5.0/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-5.0/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-5.0/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-5.0/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-5.0/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/net-client-versions.mdx b/versioned_docs/version-5.0/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-5.0/client-api/net-client-versions.mdx +++ b/versioned_docs/version-5.0/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-5.0/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-5.0/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-5.0/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-5.0/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-5.0/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-5.0/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-5.0/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-5.0/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-5.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 8eb75698fb..e5de026d99 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index b05dd86c51..0922b9c087 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/include-compare-exchange.mdx index 504daa4a02..0e3e24afd7 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/overview.mdx index 06412b791f..bd1ec58ac8 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-5.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-5.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-5.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/_delete-by-query-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/_delete-by-query-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/_delete-by-query-java.mdx b/versioned_docs/version-5.0/client-api/operations/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/_delete-by-query-java.mdx rename to versioned_docs/version-5.0/client-api/operations/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-5.0/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-5.0/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-5.0/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-5.0/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-5.0/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-5.0/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-5.0/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-5.0/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-5.0/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-5.0/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-5.0/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-5.0/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/delete-by-query.mdx b/versioned_docs/version-5.0/client-api/operations/delete-by-query.mdx index fa8a8b681d..50bc2515e9 100644 --- a/versioned_docs/version-5.0/client-api/operations/delete-by-query.mdx +++ b/versioned_docs/version-5.0/client-api/operations/delete-by-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-5.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-5.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-5.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 8b3e793df4..d066d2eb37 100644 --- a/versioned_docs/version-5.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-5.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 960030cb78..f3bc0e847d 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx index fd66f74e2b..1be313d638 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index da2a18bd7c..217f4c083c 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; -import AddConnectionStringJava from './_add-connection-string-java.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; +import AddConnectionStringJava from './content/_add-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 365c692f3c..b2d4644259 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; -import GetConnectionStringJava from './_get-connection-string-java.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; +import GetConnectionStringJava from './content/_get-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index b69ef679d2..0ffe4f8a0e 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; -import RemoveConnectionStringJava from './_remove-connection-string-java.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringJava from './content/_remove-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-collection-statistics-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-collection-statistics-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-detailed-statistics-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-detailed-statistics-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-statistics-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-statistics-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-statistics-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/_get-statistics-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/_get-statistics-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/content/_get-statistics-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/add-etl.mdx index 6b370645b3..990b55c005 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/get-collection-statistics.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/get-collection-statistics.mdx index ac33eb1e8a..aa9d87c7ce 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/get-collection-statistics.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/get-collection-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCollectionStatisticsCsharp from './_get-collection-statistics-csharp.mdx'; -import GetCollectionStatisticsJava from './_get-collection-statistics-java.mdx'; +import GetCollectionStatisticsCsharp from './content/_get-collection-statistics-csharp.mdx'; +import GetCollectionStatisticsJava from './content/_get-collection-statistics-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/get-detailed-statistics.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/get-detailed-statistics.mdx index 80e4f039ba..c9b4936927 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/get-detailed-statistics.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/get-detailed-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDetailedStatisticsCsharp from './_get-detailed-statistics-csharp.mdx'; -import GetDetailedStatisticsJava from './_get-detailed-statistics-java.mdx'; +import GetDetailedStatisticsCsharp from './content/_get-detailed-statistics-csharp.mdx'; +import GetDetailedStatisticsJava from './content/_get-detailed-statistics-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/get-statistics.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/get-statistics.mdx index 7ab59532a6..281d3a0a84 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/get-statistics.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/get-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatisticsCsharp from './_get-statistics-csharp.mdx'; -import GetStatisticsJava from './_get-statistics-java.mdx'; +import GetStatisticsCsharp from './content/_get-statistics-csharp.mdx'; +import GetStatisticsJava from './content/_get-statistics-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/identities/get-identities.mdx index 3815c90caf..6d6de5138a 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-5.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/delete-index.mdx index b7de8fa9ea..d31358936f 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/disable-index.mdx index 0c5806cf4d..6c084fd5d4 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/enable-index.mdx index 6506876348..4a238c903e 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-errors.mdx index 677b5cff6c..1f167fa168 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-names.mdx index b2335e394f..b5ae1f846f 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index.mdx index a3c77a8ac9..2a43d3f84c 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-indexes.mdx index e6179f273c..2b73a09b0d 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-terms.mdx index 1bf8971406..e76ea582dd 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/index-has-changed.mdx index 1662b2d172..7f88cbc329 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/put-indexes.mdx index 742060167b..aec419ba4e 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/reset-index.mdx index 6171b19111..034cae96a8 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-lock.mdx index a38fcd9e29..de6e64089e 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-priority.mdx index c186cbbb2a..eaf94b9e7b 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-index.mdx index 6f9fd53715..e5de41e7ca 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-indexing.mdx index 01a0c2a0e5..12c1cadfc5 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-index.mdx index bc0a9a5470..b672d7c320 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-indexing.mdx index f0d62c3000..d8186af3a8 100644 --- a/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-5.0/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-5.0/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-5.0/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/patching/set-based.mdx b/versioned_docs/version-5.0/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-5.0/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-5.0/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/patching/single-document.mdx b/versioned_docs/version-5.0/client-api/operations/patching/single-document.mdx index 6dc6e75272..b41b31d73b 100644 --- a/versioned_docs/version-5.0/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-5.0/client-api/operations/patching/single-document.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/revisions/configure-revisions.mdx b/versioned_docs/version-5.0/client-api/operations/revisions/configure-revisions.mdx index 54470ca110..09a3f0e967 100644 --- a/versioned_docs/version-5.0/client-api/operations/revisions/configure-revisions.mdx +++ b/versioned_docs/version-5.0/client-api/operations/revisions/configure-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/revisions/_configure-revisions-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/revisions/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/revisions/_configure-revisions-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/revisions/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/revisions/_configure-revisions-java.mdx b/versioned_docs/version-5.0/client-api/operations/revisions/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/revisions/_configure-revisions-java.mdx rename to versioned_docs/version-5.0/client-api/operations/revisions/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/add-database-node.mdx index 2cb4d31d60..b9fe604e59 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/add-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx index aee0d3102b..e9118cf383 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/delete-certificate.mdx index f916163c53..a533d68ca2 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx index 2527bf1aff..047f33765b 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index 3042e7dc25..3137e56b18 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index c474bd59a1..14126836c5 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/create-database.mdx index abd4d68c0d..ea75a81467 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-5.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/promote-database-node.mdx index a1b342c55a..14e10ef548 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/restore-backup.mdx index 0a28a9ca56..122865eee3 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/restore-backup.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-databases-state.mdx index 61b9d9a396..fd4c1e4e85 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-5.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/operations/what-are-operations.mdx b/versioned_docs/version-5.0/client-api/operations/what-are-operations.mdx index 7c2ad27db8..9f02c7218e 100644 --- a/versioned_docs/version-5.0/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-5.0/client-api/operations/what-are-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/cluster-transaction.mdx b/versioned_docs/version-5.0/client-api/session/cluster-transaction.mdx index 092b88a835..e2bbe60a8f 100644 --- a/versioned_docs/version-5.0/client-api/session/cluster-transaction.mdx +++ b/versioned_docs/version-5.0/client-api/session/cluster-transaction.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClusterTransactionCsharp from './_cluster-transaction-csharp.mdx'; +import ClusterTransactionCsharp from './content/_cluster-transaction-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-tracking.mdx index 2d40efb396..28de920dc6 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-5.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-5.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-5.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/_cluster-transaction-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_cluster-transaction-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_cluster-transaction-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_cluster-transaction-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-5.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-5.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-5.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/deleting-entities.mdx b/versioned_docs/version-5.0/client-api/session/deleting-entities.mdx index 7830ac0cba..5d7364f947 100644 --- a/versioned_docs/version-5.0/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-5.0/client-api/session/how-to/check-if-attachment-exists.mdx index a87cd5c6dc..ac371e05a6 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-5.0/client-api/session/how-to/check-if-document-exists.mdx index f65fc256df..100f8f8655 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/check-if-document-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-5.0/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-5.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-5.0/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-5.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-5.0/client-api/session/how-to/defer-operations.mdx index e126593869..dd839bc6af 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-5.0/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-counters.mdx index fb07410a4f..f2e8f9e4bb 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-counters.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-5.0/client-api/session/how-to/ignore-entity-changes.mdx index ec0fea1629..d46a577949 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-5.0/client-api/session/how-to/perform-operations-lazily.mdx index dcc393fa54..6005bd2cf1 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-5.0/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-5.0/client-api/session/how-to/subscribe-to-events.mdx index 8ee4d73d09..7e3b972ad5 100644 --- a/versioned_docs/version-5.0/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-5.0/client-api/session/how-to/subscribe-to-events.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/loading-entities.mdx b/versioned_docs/version-5.0/client-api/session/loading-entities.mdx index 2a39a6fb00..8214ff7506 100644 --- a/versioned_docs/version-5.0/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/opening-a-session.mdx b/versioned_docs/version-5.0/client-api/session/opening-a-session.mdx index 0b2921a7fa..bf2464701a 100644 --- a/versioned_docs/version-5.0/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-5.0/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 90b70a1b8f..0000000000 --- a/versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# How to Filter by Non-Existing Field - - -* There are situations where over time new fields are added to documents. - You may need to create a list of all of the documents that don't have these fields. - * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) - to add the missing fields. - -* To find documents with a missing field you can either: - * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) - * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) - - - -## Query a Static Index - -You can search for documents with missing fields by using a static index if it indexes the field which is -suspected to be missing in some of the documents. - -The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. - -* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, - query an index that indexes the fields `Freight` and `Id`. -* If your static index does not contain the desired field, either - * Modify your index definition to index the specific field. (This will trigger re-indexing.) - * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). - -### Example: Query a Static Index - -In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. - -#### First we need an index that includes `Freight` and a field that exists in every document - -We index the missing field `Freight` and the field `Id`, which exists in every document. -This way, the index includes all of the documents in the collection, -including those that are missing the specified field. - - - -{`// Create or modify a static index called Orders_ByFreight -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public Orders_ByFreight() - \{ - // Specify collection name - Map = orders => from doc in orders - select new - \{ - // Field that is missing in some documents - doc.Freight, - // Field that exists in all documents - doc.Id - \}; - \} -\} -`} - - - -#### Then we query the index to find documents where the field does not exist - -SAMPLE QUERY: - -Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. - - - - -{`List results = session - .Advanced - // Query the static index - .DocumentQuery() - // Verify that the index is not stale (optional) - .WaitForNonStaleResults(TimeSpan.MaxValue) - // Negate the next method - .Not - // Specify the field that is suspected to be missing - .WhereExists(x => x.Freight) - .ToList(); - // \`results\` will contain the list of incomplete documents. -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - -LINQ SYNTAX: - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **TIndexCreator** | string | The name of the index that you want to use. | -| **missingFieldName**| string | The field that is missing in some of the documents. | - - - - -## Query the Collection to Create an Auto-Index - -Another option is to query the collection for the missing field. -This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. - -See the example and query syntax descriptions below: - -### Example: A query that creates an Auto-Index - -The following query will create an auto-index on the "Freight" field -that is missing in some documents in the Orders collection. -The query result will contain all documents that do not have this field. - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("Freight") - .ToList(); -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - -#### LINQ Query Syntax - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **missingFieldName** | string | The field that is missing in some of the documents. | - - - - - -## Use Studio to filter by non-existing field - -You can also use Studio to find missing fields with an RQL query such as: - -``` -from "Orders" -where exists("Company") and not exists("Freight") -``` - -In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. -Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), -we must first call a field that exists in every document in the collection -and then the field that does not exist in some of them. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu items. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created for this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not have the specified field. - (The field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx deleted file mode 100644 index 17f9666668..0000000000 --- a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx +++ /dev/null @@ -1,549 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of -spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, -and `OrderByDistanceDescending`. - -* In this page: - * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) - * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) - * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - - -## Spatial - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | - -### DynamicSpatialFieldFactory - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | -| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in index | -| **fieldName** | `string` | Path to spatial field in index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - -### Example II - -This example demonstrates rounding. The query sorts the results by distance from -the specified point, but rounds the distance up to the nearest 100 km interval. -All results within the same interval are sorted alphabetically by the field `Name`. - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = session - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToList(); -`} - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToListAsync(); -`} - - - - -{`from Houses as h -order by spatial.distance( - spatial.point(h.Latitude, h.Longitude), - spatial.point(32.1234, 23.4321), - 100), h.Name -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx deleted file mode 100644 index 9c5caf9969..0000000000 --- a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..68ea5e01e7 --- /dev/null +++ b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# How to Filter by Non-Existing Field + + +* There are situations where over time new fields are added to documents. + You may need to create a list of all of the documents that don't have these fields. + * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) + to add the missing fields. + +* To find documents with a missing field you can either: + * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) + * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) + + + +## Query a Static Index + +You can search for documents with missing fields by using a static index if it indexes the field which is +suspected to be missing in some of the documents. + +The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. + +* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, + query an index that indexes the fields `Freight` and `Id`. +* If your static index does not contain the desired field, either + * Modify your index definition to index the specific field. (This will trigger re-indexing.) + * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). + +### Example: Query a Static Index + +In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. + +#### First we need an index that includes `Freight` and a field that exists in every document + +We index the missing field `Freight` and the field `Id`, which exists in every document. +This way, the index includes all of the documents in the collection, +including those that are missing the specified field. + + + +{`// Create or modify a static index called Orders_ByFreight +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public Orders_ByFreight() + \{ + // Specify collection name + Map = orders => from doc in orders + select new + \{ + // Field that is missing in some documents + doc.Freight, + // Field that exists in all documents + doc.Id + \}; + \} +\} +`} + + + +#### Then we query the index to find documents where the field does not exist + +SAMPLE QUERY: + +Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. + + + + +{`List results = session + .Advanced + // Query the static index + .DocumentQuery() + // Verify that the index is not stale (optional) + .WaitForNonStaleResults(TimeSpan.MaxValue) + // Negate the next method + .Not + // Specify the field that is suspected to be missing + .WhereExists(x => x.Freight) + .ToList(); + // \`results\` will contain the list of incomplete documents. +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + +LINQ SYNTAX: + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **TIndexCreator** | string | The name of the index that you want to use. | +| **missingFieldName**| string | The field that is missing in some of the documents. | + + + + +## Query the Collection to Create an Auto-Index + +Another option is to query the collection for the missing field. +This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. + +See the example and query syntax descriptions below: + +### Example: A query that creates an Auto-Index + +The following query will create an auto-index on the "Freight" field +that is missing in some documents in the Orders collection. +The query result will contain all documents that do not have this field. + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("Freight") + .ToList(); +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + +#### LINQ Query Syntax + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **missingFieldName** | string | The field that is missing in some of the documents. | + + + + + +## Use Studio to filter by non-existing field + +You can also use Studio to find missing fields with an RQL query such as: + +``` +from "Orders" +where exists("Company") and not exists("Freight") +``` + +In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. +Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), +we must first call a field that exists in every document in the collection +and then the field that does not exist in some of them. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu items. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created for this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not have the specified field. + (The field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-proximity-search-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-proximity-search-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx new file mode 100644 index 0000000000..f76839a4dc --- /dev/null +++ b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx @@ -0,0 +1,549 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of +spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, +and `OrderByDistanceDescending`. + +* In this page: + * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) + * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) + * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + + +## Spatial + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | + +### DynamicSpatialFieldFactory + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | +| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in index | +| **fieldName** | `string` | Path to spatial field in index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + +### Example II + +This example demonstrates rounding. The query sorts the results by distance from +the specified point, but rounds the distance up to the nearest 100 km interval. +All results within the same interval are sorted alphabetically by the field `Name`. + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = session + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToList(); +`} + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToListAsync(); +`} + + + + +{`from Houses as h +order by spatial.distance( + spatial.point(h.Latitude, h.Longitude), + spatial.point(32.1234, 23.4321), + 100), h.Name +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx new file mode 100644 index 0000000000..2396725492 --- /dev/null +++ b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-fuzzy-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-fuzzy-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-regex-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index a64e783cc2..0000000000 --- a/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery Timings(out QueryTimings timings); -`} - - - -## Example - - - - -{`var resultWithTimings = session.Advanced.DocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToList(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToListAsync(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index a85ad6f470..0000000000 --- a/versioned_docs/version-5.0/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..b777106c96 --- /dev/null +++ b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,57 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery Timings(out QueryTimings timings); +`} + + + +## Example + + + + +{`var resultWithTimings = session.Advanced.DocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToList(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToListAsync(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..99f3fa91d6 --- /dev/null +++ b/versioned_docs/version-5.0/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/include-explanations.mdx index ec808ee6a9..4df35b7773 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/debugging/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-5.0/client-api/session/querying/debugging/query-timings.mdx index 945f73958f..7986688800 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/debugging/query-timings.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-5.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-5.0/client-api/session/querying/document-query/what-is-document-query.mdx index cef08c1c05..798546d402 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-customize-query.mdx index 2e9f4cd49b..d8110e41f3 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-field.mdx index f0ff8185c2..285ee08861 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 38b64f0c4f..d194cb8bcf 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-get-query-statistics.mdx index 83a9c90774..433e7bbfad 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 2671c19cf6..08c52105c3 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-proximity-search.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-proximity-search.mdx index ddaa663299..622e2335b3 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-proximity-search.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-proximity-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProximitySearchCsharp from './_how-to-perform-proximity-search-csharp.mdx'; -import HowToPerformProximitySearchJava from './_how-to-perform-proximity-search-java.mdx'; +import HowToPerformProximitySearchCsharp from './content/_how-to-perform-proximity-search-csharp.mdx'; +import HowToPerformProximitySearchJava from './content/_how-to-perform-proximity-search-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-queries-lazily.mdx index e32d80e161..81bbc4fa19 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-project-query-results.mdx index 4064387648..9c7d07ff5c 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-query-a-spatial-index.mdx index a61668f911..2a328088f5 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-query-with-exact-match.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-query-with-exact-match.mdx index 29dadbe6eb..c6befd9e24 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-query-with-exact-match.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-query-with-exact-match.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryWithExactMatchCsharp from './_how-to-query-with-exact-match-csharp.mdx'; -import HowToQueryWithExactMatchJava from './_how-to-query-with-exact-match-java.mdx'; -import HowToQueryWithExactMatchNodejs from './_how-to-query-with-exact-match-nodejs.mdx'; +import HowToQueryWithExactMatchCsharp from './content/_how-to-query-with-exact-match-csharp.mdx'; +import HowToQueryWithExactMatchJava from './content/_how-to-query-with-exact-match-java.mdx'; +import HowToQueryWithExactMatchNodejs from './content/_how-to-query-with-exact-match-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-query.mdx index 5338135aad..65f0860b27 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-stream-query-results.mdx index 75d86a60b2..69bde8d43d 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-fuzzy.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-fuzzy.mdx index 1b18017dcb..9d2276243c 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-fuzzy.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-fuzzy.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseFuzzyCsharp from './_how-to-use-fuzzy-csharp.mdx'; -import HowToUseFuzzyJava from './_how-to-use-fuzzy-java.mdx'; +import HowToUseFuzzyCsharp from './content/_how-to-use-fuzzy-csharp.mdx'; +import HowToUseFuzzyJava from './content/_how-to-use-fuzzy-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-highlighting.mdx index 93ef8a0c20..a03a38aeea 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-regex.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-regex.mdx index d46f82cab1..e0e9f41896 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-regex.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseRegexCsharp from './_how-to-use-regex-csharp.mdx'; -import HowToUseRegexJava from './_how-to-use-regex-java.mdx'; -import HowToUseRegexNodejs from './_how-to-use-regex-nodejs.mdx'; +import HowToUseRegexCsharp from './content/_how-to-use-regex-csharp.mdx'; +import HowToUseRegexJava from './content/_how-to-use-regex-java.mdx'; +import HowToUseRegexNodejs from './content/_how-to-use-regex-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-search.mdx index 8e128dfebb..eab93a36f4 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-use-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-5.0/client-api/session/querying/how-to-work-with-suggestions.mdx index dfc2413f17..c15846553c 100644 --- a/versioned_docs/version-5.0/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-5.0/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_counter-revisions-csharp.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_counter-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_counter-revisions-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_counter-revisions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_counter-revisions-java.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_counter-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_counter-revisions-java.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_counter-revisions-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-5.0/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.0/client-api/session/revisions/counter-revisions.mdx b/versioned_docs/version-5.0/client-api/session/revisions/counter-revisions.mdx index 2685ffaefe..096cb444a7 100644 --- a/versioned_docs/version-5.0/client-api/session/revisions/counter-revisions.mdx +++ b/versioned_docs/version-5.0/client-api/session/revisions/counter-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterRevisionsCsharp from './_counter-revisions-csharp.mdx'; -import CounterRevisionsJava from './_counter-revisions-java.mdx'; +import CounterRevisionsCsharp from './content/_counter-revisions-csharp.mdx'; +import CounterRevisionsJava from './content/_counter-revisions-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/revisions/loading.mdx b/versioned_docs/version-5.0/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-5.0/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-5.0/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-5.0/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-5.0/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-5.0/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/saving-changes.mdx b/versioned_docs/version-5.0/client-api/session/saving-changes.mdx index b2f757ca4c..190869532f 100644 --- a/versioned_docs/version-5.0/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-5.0/client-api/session/saving-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/storing-entities.mdx b/versioned_docs/version-5.0/client-api/session/storing-entities.mdx index 09787c1800..dafb1abe29 100644 --- a/versioned_docs/version-5.0/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/updating-entities.mdx b/versioned_docs/version-5.0/client-api/session/updating-entities.mdx index c7a719d596..58a56a1004 100644 --- a/versioned_docs/version-5.0/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-5.0/client-api/session/updating-entities.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-5.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx index 1eb9ad91cf..c17516971d 100644 --- a/versioned_docs/version-5.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-5.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-5.0/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-5.0/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-5.0/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-5.0/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/setting-up-default-database.mdx b/versioned_docs/version-5.0/client-api/setting-up-default-database.mdx index 75fc4c2450..b217f301b3 100644 --- a/versioned_docs/version-5.0/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-5.0/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-5.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-5.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-5.0/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-5.0/client-api/smuggler/what-is-smuggler.mdx index f1af37fb68..da1d8be3d1 100644 --- a/versioned_docs/version-5.0/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-5.0/client-api/smuggler/what-is-smuggler.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; diff --git a/versioned_docs/version-5.0/client-api/what-is-a-document-store.mdx b/versioned_docs/version-5.0/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-5.0/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-5.0/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-5.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-5.0/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-5.0/document-extensions/attachments/copying-moving-renaming.mdx index b9774d0444..65484c9d78 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/deleting.mdx b/versioned_docs/version-5.0/document-extensions/attachments/deleting.mdx index 6259980cd3..3a916d6185 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/indexing.mdx b/versioned_docs/version-5.0/document-extensions/attachments/indexing.mdx index 8e31915c92..a30109af32 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/loading.mdx b/versioned_docs/version-5.0/document-extensions/attachments/loading.mdx index 9df0597641..13d7ce3ad5 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/storing.mdx b/versioned_docs/version-5.0/document-extensions/attachments/storing.mdx index 63f3d6f602..f9646cbe1f 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-5.0/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-5.0/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-5.0/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-5.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-5.0/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-5.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-5.0/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-5.0/document-extensions/counters/counters-and-other-features.mdx index 259d3ba4c4..649445d40a 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/counters-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-5.0/document-extensions/counters/create-or-modify.mdx index 5e8c29ec4a..8f8d71dfef 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/delete.mdx b/versioned_docs/version-5.0/document-extensions/counters/delete.mdx index 949fb2feed..d1e2ffe8a1 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/indexing.mdx b/versioned_docs/version-5.0/document-extensions/counters/indexing.mdx index db35f0ea83..ff4eebfdea 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/indexing.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/overview.mdx b/versioned_docs/version-5.0/document-extensions/counters/overview.mdx index bf20ec9bcd..50c52e0ffe 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.0/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-5.0/document-extensions/counters/retrieve-counter-values.mdx index acd7025f97..669bcfbff9 100644 --- a/versioned_docs/version-5.0/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-5.0/document-extensions/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-5.0/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-5.0/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-5.0/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-5.0/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_index-query-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_index-query-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_query-result-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_query-result-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/_stream-result-csharp.mdx b/versioned_docs/version-5.0/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-5.0/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-5.0/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-5.0/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-5.0/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/counters-batch-command-data.mdx b/versioned_docs/version-5.0/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-5.0/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/delete-command-data.mdx b/versioned_docs/version-5.0/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-5.0/glossary/delete-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-5.0/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-5.0/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/index-query.mdx b/versioned_docs/version-5.0/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-5.0/glossary/index-query.mdx +++ b/versioned_docs/version-5.0/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/move-attachment-command-data.mdx b/versioned_docs/version-5.0/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-5.0/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/patch-command-data.mdx b/versioned_docs/version-5.0/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-5.0/glossary/patch-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/put-command-data.mdx b/versioned_docs/version-5.0/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-5.0/glossary/put-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-5.0/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-5.0/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.0/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/query-result.mdx b/versioned_docs/version-5.0/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-5.0/glossary/query-result.mdx +++ b/versioned_docs/version-5.0/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/stream-query-statistics.mdx b/versioned_docs/version-5.0/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-5.0/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-5.0/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-5.0/glossary/stream-result.mdx b/versioned_docs/version-5.0/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-5.0/glossary/stream-result.mdx +++ b/versioned_docs/version-5.0/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/_fanout-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/_fanout-indexes-csharp.mdx deleted file mode 100644 index 94f6065246..0000000000 --- a/versioned_docs/version-5.0/indexes/_fanout-indexes-csharp.mdx +++ /dev/null @@ -1,171 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public class Orders_ByProduct : AbstractIndexCreationTask -{ - public Orders_ByProduct() - { - Map = orders => from order in orders - from orderLine in order.Lines - select new - { - orderLine.Product, - orderLine.ProductName - }; - } -} -`} - - - - -{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByProduct() - { - Maps = new HashSet - { - @"map('Orders', function (order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - ProductName: l.ProductName - }) - }); - return res; - })", - }; - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public class Product_Sales : AbstractIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - public int Count { get; set; } - public decimal Total; - } - - public Product_Sales() - { - Map = orders => from order in orders - from line in order.Lines - select new Result - { - Product = line.Product, - Count = 1, - Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) - }; - - Reduce = results => from result in results - group result by result.Product - into g - select new - { - Product = g.Key, - Count = g.Sum(x => x.Count), - Total = g.Sum(x => x.Total) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.0/indexes/_fanout-indexes-java.mdx b/versioned_docs/version-5.0/indexes/_fanout-indexes-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-5.0/indexes/_fanout-indexes-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-5.0/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.0/indexes/boosting.mdx b/versioned_docs/version-5.0/indexes/boosting.mdx index 63937b73b3..4e299192ad 100644 --- a/versioned_docs/version-5.0/indexes/boosting.mdx +++ b/versioned_docs/version-5.0/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/_boosting-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_boosting-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_boosting-java.mdx b/versioned_docs/version-5.0/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_boosting-java.mdx rename to versioned_docs/version-5.0/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_boosting-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_extending-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/content/_fanout-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_fanout-indexes-csharp.mdx new file mode 100644 index 0000000000..bb8d3382d9 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/content/_fanout-indexes-csharp.mdx @@ -0,0 +1,171 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public class Orders_ByProduct : AbstractIndexCreationTask +{ + public Orders_ByProduct() + { + Map = orders => from order in orders + from orderLine in order.Lines + select new + { + orderLine.Product, + orderLine.ProductName + }; + } +} +`} + + + + +{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByProduct() + { + Maps = new HashSet + { + @"map('Orders', function (order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + ProductName: l.ProductName + }) + }); + return res; + })", + }; + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public class Product_Sales : AbstractIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + public int Count { get; set; } + public decimal Total; + } + + public Product_Sales() + { + Map = orders => from order in orders + from line in order.Lines + select new Result + { + Product = line.Product, + Count = 1, + Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) + }; + + Reduce = results => from result in results + group result by result.Product + into g + select new + { + Product = g.Key, + Count = g.Sum(x => x.Count), + Total = g.Sum(x => x.Total) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.0/indexes/content/_fanout-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_fanout-indexes-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/content/_fanout-indexes-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.0/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-basics-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-hierarchical-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-hierarchical-data-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-hierarchical-data-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.0/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-related-documents-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-related-documents-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-related-documents-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-5.0/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-5.0/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-5.0/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-5.0/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_stale-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-5.0/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-5.0/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-analyzers-java.mdx b/versioned_docs/version-5.0/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-5.0/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_using-dynamic-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-dynamic-fields-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_using-dynamic-fields-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.0/indexes/content/_using-dynamic-fields-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-dynamic-fields-java.mdx rename to versioned_docs/version-5.0/indexes/content/_using-dynamic-fields-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-5.0/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-5.0/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.0/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-5.0/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-5.0/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-5.0/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-5.0/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.0/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-5.0/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-5.0/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-5.0/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-5.0/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/creating-and-deploying.mdx b/versioned_docs/version-5.0/indexes/creating-and-deploying.mdx index ad82e6dc99..e0eebf6640 100644 --- a/versioned_docs/version-5.0/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-5.0/indexes/creating-and-deploying.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/extending-indexes.mdx b/versioned_docs/version-5.0/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-5.0/indexes/extending-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/fanout-indexes.mdx b/versioned_docs/version-5.0/indexes/fanout-indexes.mdx index c07252a661..c76c4ee85f 100644 --- a/versioned_docs/version-5.0/indexes/fanout-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/fanout-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FanoutIndexesCsharp from './_fanout-indexes-csharp.mdx'; -import FanoutIndexesJava from './_fanout-indexes-java.mdx'; +import FanoutIndexesCsharp from './content/_fanout-indexes-csharp.mdx'; +import FanoutIndexesJava from './content/_fanout-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-basics.mdx b/versioned_docs/version-5.0/indexes/indexing-basics.mdx index 72b153a25f..15560b37fc 100644 --- a/versioned_docs/version-5.0/indexes/indexing-basics.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-5.0/indexes/indexing-compare-exchange-values.mdx index bfca9ab956..00bd3cebc8 100644 --- a/versioned_docs/version-5.0/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-compare-exchange-values.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-5.0/indexes/indexing-hierarchical-data.mdx index ebe167fdaa..b0481950bf 100644 --- a/versioned_docs/version-5.0/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-hierarchical-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-5.0/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-5.0/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-5.0/indexes/indexing-polymorphic-data.mdx index bddb362a3a..4c08de81be 100644 --- a/versioned_docs/version-5.0/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-related-documents.mdx b/versioned_docs/version-5.0/indexes/indexing-related-documents.mdx index 528f4459ea..b8cec71b26 100644 --- a/versioned_docs/version-5.0/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-related-documents.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/indexing-spatial-data.mdx b/versioned_docs/version-5.0/indexes/indexing-spatial-data.mdx index 7f0511363d..caca7442e3 100644 --- a/versioned_docs/version-5.0/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-5.0/indexes/indexing-spatial-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/javascript-indexes.mdx b/versioned_docs/version-5.0/indexes/javascript-indexes.mdx index 7317155649..44909a2261 100644 --- a/versioned_docs/version-5.0/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/map-indexes.mdx b/versioned_docs/version-5.0/indexes/map-indexes.mdx index e65cd6bd51..d0ca5316e0 100644 --- a/versioned_docs/version-5.0/indexes/map-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/map-indexes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/map-reduce-indexes.mdx b/versioned_docs/version-5.0/indexes/map-reduce-indexes.mdx index 67f28f3ee9..b0226e7feb 100644 --- a/versioned_docs/version-5.0/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/map-reduce-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/multi-map-indexes.mdx b/versioned_docs/version-5.0/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-5.0/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/number-type-conversion.mdx b/versioned_docs/version-5.0/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-5.0/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-5.0/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index dfeeef4291..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **Cost** field, return the count of the following ranges: - - * Cost < 200.0 - * 200.0 <= Cost < 400.0 - * 400.0 <= Cost < 600.0 - * 600.0 <= Cost < 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels < 7.0 - * 7.0 <= Megapixels < 10.0 - * Megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(Manufacturer), - facet(Cost <= 200, - Cost between 200 and 400, - Cost between 400 and 600, Cost between 600 and 800, - Cost >= 800), - facet(Megapixels <= 3, - Megapixels between 3 and 7, - Megapixels between 7 and 10, - Megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "Manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "Cost", - "Values": [ - \{ - "Count": 6, - "Range": "Cost <= 200" - \}, - \{ - "Count": 2, - "Range": "Cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "Cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "Cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "Cost >= 800" - \} - ] - \}, - \{ - "Name": "Megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "Megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "Megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "Megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "Megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-5.0/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ecb4312302..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.0/indexes/querying/_paging-java.mdx b/versioned_docs/version-5.0/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.0/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index e52c0cff7a..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a Fanout index. - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.0/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/_spatial-csharp.mdx deleted file mode 100644 index b8e29cae09..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_spatial-csharp.mdx +++ /dev/null @@ -1,165 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `RelatesToShape` - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .Query() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`public class Events_ByCoordinates : AbstractIndexCreationTask -{ - public Events_ByCoordinates() - { - Map = events => from e in events - select new - { - Coordinates = CreateSpatialField(e.Latitude, e.Longitude) - }; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(Coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.0/indexes/querying/_spatial-java.mdx b/versioned_docs/version-5.0/indexes/querying/_spatial-java.mdx deleted file mode 100644 index 052325a8dc..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.0/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/_spatial-nodejs.mdx deleted file mode 100644 index 77542032c5..0000000000 --- a/versioned_docs/version-5.0/indexes/querying/_spatial-nodejs.mdx +++ /dev/null @@ -1,122 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape()` - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - "Within" - )) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`const results = await session - .query({ indexName: "Events/ByCoordinates" }) - .spatial("coordinates", - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`class Events_ByCoordinates extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Events.Select(e => new { - Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) - })\`; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.0/indexes/querying/basics.mdx b/versioned_docs/version-5.0/indexes/querying/basics.mdx index f1cbf38302..23f7507680 100644 --- a/versioned_docs/version-5.0/indexes/querying/basics.mdx +++ b/versioned_docs/version-5.0/indexes/querying/basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; -import BasicsNodejs from './_basics-nodejs.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; +import BasicsNodejs from './content/_basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/boosting.mdx b/versioned_docs/version-5.0/indexes/querying/boosting.mdx index 97dc2a028f..35a0a0b712 100644 --- a/versioned_docs/version-5.0/indexes/querying/boosting.mdx +++ b/versioned_docs/version-5.0/indexes/querying/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_basics-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_basics-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_basics-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_basics-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_basics-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_boosting-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_boosting-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_boosting-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_boosting-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_boosting-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_boosting-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_distinct-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..beb2d2de99 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **Cost** field, return the count of the following ranges: + + * Cost < 200.0 + * 200.0 <= Cost < 400.0 + * 400.0 <= Cost < 600.0 + * 600.0 <= Cost < 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels < 7.0 + * 7.0 <= Megapixels < 10.0 + * Megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(Manufacturer), + facet(Cost <= 200, + Cost between 200 and 400, + Cost between 400 and 600, Cost between 600 and 800, + Cost >= 800), + facet(Megapixels <= 3, + Megapixels between 3 and 7, + Megapixels between 7 and 10, + Megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "Manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "Cost", + "Values": [ + \{ + "Count": 6, + "Range": "Cost <= 200" + \}, + \{ + "Count": 2, + "Range": "Cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "Cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "Cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "Cost >= 800" + \} + ] + \}, + \{ + "Name": "Megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "Megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "Megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "Megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "Megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-5.0/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_filtering-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_intersection-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..967fb68620 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.0/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.0/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2cc2e022a --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a Fanout index. + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.0/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_projections-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_projections-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_sorting-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/content/_spatial-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_spatial-csharp.mdx new file mode 100644 index 0000000000..1062993808 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_spatial-csharp.mdx @@ -0,0 +1,165 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `RelatesToShape` + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .Query() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`public class Events_ByCoordinates : AbstractIndexCreationTask +{ + public Events_ByCoordinates() + { + Map = events => from e in events + select new + { + Coordinates = CreateSpatialField(e.Latitude, e.Longitude) + }; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(Coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.0/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..9c11a03099 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.0/indexes/querying/content/_spatial-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_spatial-nodejs.mdx new file mode 100644 index 0000000000..9e318daef2 --- /dev/null +++ b/versioned_docs/version-5.0/indexes/querying/content/_spatial-nodejs.mdx @@ -0,0 +1,122 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape()` + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + "Within" + )) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`const results = await session + .query({ indexName: "Events/ByCoordinates" }) + .spatial("coordinates", + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`class Events_ByCoordinates extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Events.Select(e => new { + Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) + })\`; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.0/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-5.0/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-5.0/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-5.0/indexes/querying/content/_suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.0/indexes/querying/_suggestions-nodejs.mdx rename to versioned_docs/version-5.0/indexes/querying/content/_suggestions-nodejs.mdx diff --git a/versioned_docs/version-5.0/indexes/querying/distinct.mdx b/versioned_docs/version-5.0/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-5.0/indexes/querying/distinct.mdx +++ b/versioned_docs/version-5.0/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/faceted-search.mdx b/versioned_docs/version-5.0/indexes/querying/faceted-search.mdx index 2886577ee1..427d2f26d2 100644 --- a/versioned_docs/version-5.0/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-5.0/indexes/querying/faceted-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/filtering.mdx b/versioned_docs/version-5.0/indexes/querying/filtering.mdx index c1c3bf3139..ba11c389e5 100644 --- a/versioned_docs/version-5.0/indexes/querying/filtering.mdx +++ b/versioned_docs/version-5.0/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/highlighting.mdx b/versioned_docs/version-5.0/indexes/querying/highlighting.mdx index caddfb8b7c..98d011b0fb 100644 --- a/versioned_docs/version-5.0/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-5.0/indexes/querying/highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/intersection.mdx b/versioned_docs/version-5.0/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-5.0/indexes/querying/intersection.mdx +++ b/versioned_docs/version-5.0/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/morelikethis.mdx b/versioned_docs/version-5.0/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-5.0/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-5.0/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/paging.mdx b/versioned_docs/version-5.0/indexes/querying/paging.mdx index 4a4f877127..1375a3d67e 100644 --- a/versioned_docs/version-5.0/indexes/querying/paging.mdx +++ b/versioned_docs/version-5.0/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/projections.mdx b/versioned_docs/version-5.0/indexes/querying/projections.mdx index f358bb4489..84724cf411 100644 --- a/versioned_docs/version-5.0/indexes/querying/projections.mdx +++ b/versioned_docs/version-5.0/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-5.0/indexes/querying/query-vs-document-query.mdx index b766203269..8d99869330 100644 --- a/versioned_docs/version-5.0/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-5.0/indexes/querying/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/searching.mdx b/versioned_docs/version-5.0/indexes/querying/searching.mdx index 2f747d4661..fb4145a63d 100644 --- a/versioned_docs/version-5.0/indexes/querying/searching.mdx +++ b/versioned_docs/version-5.0/indexes/querying/searching.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/sorting.mdx b/versioned_docs/version-5.0/indexes/querying/sorting.mdx index a230093906..fc72ce4f44 100644 --- a/versioned_docs/version-5.0/indexes/querying/sorting.mdx +++ b/versioned_docs/version-5.0/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/spatial.mdx b/versioned_docs/version-5.0/indexes/querying/spatial.mdx index 1e4e0092b9..5df771eb7a 100644 --- a/versioned_docs/version-5.0/indexes/querying/spatial.mdx +++ b/versioned_docs/version-5.0/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/querying/suggestions.mdx b/versioned_docs/version-5.0/indexes/querying/suggestions.mdx index 8e46c2ed39..d5209e47da 100644 --- a/versioned_docs/version-5.0/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-5.0/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/sorting-and-collation.mdx b/versioned_docs/version-5.0/indexes/sorting-and-collation.mdx index c55cbb45c0..f3c27ca9c0 100644 --- a/versioned_docs/version-5.0/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-5.0/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/stale-indexes.mdx b/versioned_docs/version-5.0/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-5.0/indexes/stale-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/storing-data-in-index.mdx b/versioned_docs/version-5.0/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-5.0/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-5.0/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/using-analyzers.mdx b/versioned_docs/version-5.0/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-5.0/indexes/using-analyzers.mdx +++ b/versioned_docs/version-5.0/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/using-dynamic-fields.mdx b/versioned_docs/version-5.0/indexes/using-dynamic-fields.mdx index b35ee6b88e..b6d6b98cf2 100644 --- a/versioned_docs/version-5.0/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-5.0/indexes/using-dynamic-fields.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; diff --git a/versioned_docs/version-5.0/indexes/using-term-vectors.mdx b/versioned_docs/version-5.0/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-5.0/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-5.0/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/indexes/what-are-indexes.mdx b/versioned_docs/version-5.0/indexes/what-are-indexes.mdx index baeb219b47..613babe12e 100644 --- a/versioned_docs/version-5.0/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-5.0/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.0/server/_embedded-csharp.mdx b/versioned_docs/version-5.0/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/server/_embedded-csharp.mdx rename to versioned_docs/version-5.0/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-5.0/server/_embedded-java.mdx b/versioned_docs/version-5.0/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-5.0/server/_embedded-java.mdx rename to versioned_docs/version-5.0/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-5.0/server/embedded.mdx b/versioned_docs/version-5.0/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-5.0/server/embedded.mdx +++ b/versioned_docs/version-5.0/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-5.0/start/_test-driver-csharp.mdx b/versioned_docs/version-5.0/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.0/start/_test-driver-csharp.mdx rename to versioned_docs/version-5.0/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-5.0/start/_test-driver-java.mdx b/versioned_docs/version-5.0/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-5.0/start/_test-driver-java.mdx rename to versioned_docs/version-5.0/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-5.0/start/test-driver.mdx b/versioned_docs/version-5.0/start/test-driver.mdx index caaf54ab4c..76d2299c77 100644 --- a/versioned_docs/version-5.0/start/test-driver.mdx +++ b/versioned_docs/version-5.0/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-5.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-5.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index 2da0998998..7a7756c6fa 100644 --- a/versioned_docs/version-5.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-5.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-5.1/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-5.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-5.1/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-5.1/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-5.1/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-5.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-5.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-5.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-5.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-5.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-5.1/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-5.1/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-5.1/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-5.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 5067204d77..d6621b1518 100644 --- a/versioned_docs/version-5.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-5.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-5.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-5.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-5.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-5.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-5.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 3fbea43e2e..eaccf2717d 100644 --- a/versioned_docs/version-5.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-5.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-5.1/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/delete.mdx b/versioned_docs/version-5.1/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-5.1/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-5.1/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/commands/documents/get.mdx b/versioned_docs/version-5.1/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-5.1/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-5.1/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-5.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-5.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-5.1/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-5.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-5.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-5.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-5.1/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/commands/documents/put.mdx b/versioned_docs/version-5.1/client-api/commands/documents/put.mdx index bf35d76f41..0b47252188 100644 --- a/versioned_docs/version-5.1/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-5.1/client-api/commands/documents/put.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-java.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-java.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-java.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-nodejs.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_load-balance-and-failover-nodejs.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_load-balance-and-failover-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_querying-java.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-5.1/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-5.1/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/conventions.mdx b/versioned_docs/version-5.1/client-api/configuration/conventions.mdx index 69915fbd4d..5882c3f020 100644 --- a/versioned_docs/version-5.1/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/conventions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-5.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-5.1/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/load-balance-and-failover.mdx b/versioned_docs/version-5.1/client-api/configuration/load-balance-and-failover.mdx index 677cdab7a6..39c9ec118b 100644 --- a/versioned_docs/version-5.1/client-api/configuration/load-balance-and-failover.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/load-balance-and-failover.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceAndFailoverCsharp from './_load-balance-and-failover-csharp.mdx'; -import LoadBalanceAndFailoverJava from './_load-balance-and-failover-java.mdx'; -import LoadBalanceAndFailoverNodejs from './_load-balance-and-failover-nodejs.mdx'; +import LoadBalanceAndFailoverCsharp from './content/_load-balance-and-failover-csharp.mdx'; +import LoadBalanceAndFailoverJava from './content/_load-balance-and-failover-java.mdx'; +import LoadBalanceAndFailoverNodejs from './content/_load-balance-and-failover-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/querying.mdx b/versioned_docs/version-5.1/client-api/configuration/querying.mdx index c758060e9b..f5bb516607 100644 --- a/versioned_docs/version-5.1/client-api/configuration/querying.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/configuration/serialization.mdx b/versioned_docs/version-5.1/client-api/configuration/serialization.mdx index 7b97467d9e..f531b1b2d0 100644 --- a/versioned_docs/version-5.1/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-5.1/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-5.1/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-5.1/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-5.1/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-5.1/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-5.1/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-5.1/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-5.1/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-5.1/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-5.1/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/creating-document-store.mdx b/versioned_docs/version-5.1/client-api/creating-document-store.mdx index c3703c0c2c..5132778fb7 100644 --- a/versioned_docs/version-5.1/client-api/creating-document-store.mdx +++ b/versioned_docs/version-5.1/client-api/creating-document-store.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index 545845e219..b9549d42f0 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d296754727..46beae2231 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 04fcd004d3..c0af55d828 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/api-overview.mdx index 460655150d..e05c87edf4 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-5.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/examples.mdx index ca8c2f97c2..d5c631951d 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/examples.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-5.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-5.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-5.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-5.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-5.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-5.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-5.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-5.1/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-5.1/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-5.1/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-5.1/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-5.1/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-5.1/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-5.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-5.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-5.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-5.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-5.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-5.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-5.1/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-5.1/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-5.1/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-5.1/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-5.1/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-5.1/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-5.1/client-api/how-to/handle-document-relationships.mdx index b9011b331e..1358702054 100644 --- a/versioned_docs/version-5.1/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-5.1/client-api/how-to/handle-document-relationships.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-5.1/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-5.1/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-5.1/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-5.1/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-5.1/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-5.1/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/net-client-versions.mdx b/versioned_docs/version-5.1/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-5.1/client-api/net-client-versions.mdx +++ b/versioned_docs/version-5.1/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-5.1/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-5.1/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-5.1/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-5.1/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-5.1/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-5.1/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-5.1/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-5.1/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-5.1/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 8eb75698fb..e5de026d99 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index b05dd86c51..0922b9c087 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/include-compare-exchange.mdx index 504daa4a02..0e3e24afd7 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/overview.mdx index 06412b791f..bd1ec58ac8 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-5.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-5.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-5.1/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/_delete-by-query-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/_delete-by-query-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/_delete-by-query-java.mdx b/versioned_docs/version-5.1/client-api/operations/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/_delete-by-query-java.mdx rename to versioned_docs/version-5.1/client-api/operations/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-5.1/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-5.1/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-5.1/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-5.1/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-5.1/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-5.1/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-5.1/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-5.1/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-5.1/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-5.1/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-5.1/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-5.1/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/delete-by-query.mdx b/versioned_docs/version-5.1/client-api/operations/delete-by-query.mdx index fa8a8b681d..50bc2515e9 100644 --- a/versioned_docs/version-5.1/client-api/operations/delete-by-query.mdx +++ b/versioned_docs/version-5.1/client-api/operations/delete-by-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-5.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-5.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-5.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 8b3e793df4..d066d2eb37 100644 --- a/versioned_docs/version-5.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-5.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 960030cb78..f3bc0e847d 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx index fd66f74e2b..1be313d638 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index da2a18bd7c..217f4c083c 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; -import AddConnectionStringJava from './_add-connection-string-java.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; +import AddConnectionStringJava from './content/_add-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_add-connection-string-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_get-connection-string-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 365c692f3c..b2d4644259 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; -import GetConnectionStringJava from './_get-connection-string-java.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; +import GetConnectionStringJava from './content/_get-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index b69ef679d2..0ffe4f8a0e 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; -import RemoveConnectionStringJava from './_remove-connection-string-java.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringJava from './content/_remove-connection-string-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-collection-statistics-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-collection-statistics-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-collection-statistics-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-collection-statistics-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-collection-statistics-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-detailed-statistics-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-detailed-statistics-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-detailed-statistics-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-detailed-statistics-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-detailed-statistics-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-statistics-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-statistics-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-statistics-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/_get-statistics-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/_get-statistics-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/content/_get-statistics-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/add-etl.mdx index 6b370645b3..990b55c005 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/get-collection-statistics.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/get-collection-statistics.mdx index ac33eb1e8a..aa9d87c7ce 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/get-collection-statistics.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/get-collection-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCollectionStatisticsCsharp from './_get-collection-statistics-csharp.mdx'; -import GetCollectionStatisticsJava from './_get-collection-statistics-java.mdx'; +import GetCollectionStatisticsCsharp from './content/_get-collection-statistics-csharp.mdx'; +import GetCollectionStatisticsJava from './content/_get-collection-statistics-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/get-detailed-statistics.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/get-detailed-statistics.mdx index 80e4f039ba..c9b4936927 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/get-detailed-statistics.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/get-detailed-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDetailedStatisticsCsharp from './_get-detailed-statistics-csharp.mdx'; -import GetDetailedStatisticsJava from './_get-detailed-statistics-java.mdx'; +import GetDetailedStatisticsCsharp from './content/_get-detailed-statistics-csharp.mdx'; +import GetDetailedStatisticsJava from './content/_get-detailed-statistics-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/get-statistics.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/get-statistics.mdx index 7ab59532a6..281d3a0a84 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/get-statistics.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/get-statistics.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatisticsCsharp from './_get-statistics-csharp.mdx'; -import GetStatisticsJava from './_get-statistics-java.mdx'; +import GetStatisticsCsharp from './content/_get-statistics-csharp.mdx'; +import GetStatisticsJava from './content/_get-statistics-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/identities/get-identities.mdx index 3815c90caf..6d6de5138a 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-5.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/delete-index.mdx index b7de8fa9ea..d31358936f 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/disable-index.mdx index 0c5806cf4d..6c084fd5d4 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/enable-index.mdx index 6506876348..4a238c903e 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-errors.mdx index 677b5cff6c..1f167fa168 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-names.mdx index b2335e394f..b5ae1f846f 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index.mdx index a3c77a8ac9..2a43d3f84c 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-indexes.mdx index e6179f273c..2b73a09b0d 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-terms.mdx index 1bf8971406..e76ea582dd 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/index-has-changed.mdx index 1662b2d172..7f88cbc329 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/put-indexes.mdx index 742060167b..aec419ba4e 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/reset-index.mdx index 6171b19111..034cae96a8 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-lock.mdx index a38fcd9e29..de6e64089e 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-priority.mdx index c186cbbb2a..eaf94b9e7b 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-index.mdx index 6f9fd53715..e5de41e7ca 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-indexing.mdx index 01a0c2a0e5..12c1cadfc5 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-index.mdx index bc0a9a5470..b672d7c320 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-indexing.mdx index f0d62c3000..d8186af3a8 100644 --- a/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-5.1/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-5.1/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-5.1/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/patching/set-based.mdx b/versioned_docs/version-5.1/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-5.1/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-5.1/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/patching/single-document.mdx b/versioned_docs/version-5.1/client-api/operations/patching/single-document.mdx index 6dc6e75272..b41b31d73b 100644 --- a/versioned_docs/version-5.1/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-5.1/client-api/operations/patching/single-document.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/revisions/configure-revisions.mdx b/versioned_docs/version-5.1/client-api/operations/revisions/configure-revisions.mdx index 54470ca110..09a3f0e967 100644 --- a/versioned_docs/version-5.1/client-api/operations/revisions/configure-revisions.mdx +++ b/versioned_docs/version-5.1/client-api/operations/revisions/configure-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/revisions/_configure-revisions-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/revisions/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/revisions/_configure-revisions-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/revisions/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/revisions/_configure-revisions-java.mdx b/versioned_docs/version-5.1/client-api/operations/revisions/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/revisions/_configure-revisions-java.mdx rename to versioned_docs/version-5.1/client-api/operations/revisions/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/add-database-node.mdx index 2cb4d31d60..b9fe604e59 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/add-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx index aee0d3102b..e9118cf383 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/delete-certificate.mdx index f916163c53..a533d68ca2 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx index 2527bf1aff..047f33765b 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index 3042e7dc25..3137e56b18 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index c474bd59a1..14126836c5 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/create-database.mdx index abd4d68c0d..ea75a81467 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-5.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/promote-database-node.mdx index a1b342c55a..14e10ef548 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/restore-backup.mdx index 24de9db036..03f3285eb1 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-databases-state.mdx index 61b9d9a396..fd4c1e4e85 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-5.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/operations/what-are-operations.mdx b/versioned_docs/version-5.1/client-api/operations/what-are-operations.mdx index 7c2ad27db8..9f02c7218e 100644 --- a/versioned_docs/version-5.1/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-5.1/client-api/operations/what-are-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/cluster-transaction.mdx b/versioned_docs/version-5.1/client-api/session/cluster-transaction.mdx index 092b88a835..e2bbe60a8f 100644 --- a/versioned_docs/version-5.1/client-api/session/cluster-transaction.mdx +++ b/versioned_docs/version-5.1/client-api/session/cluster-transaction.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClusterTransactionCsharp from './_cluster-transaction-csharp.mdx'; +import ClusterTransactionCsharp from './content/_cluster-transaction-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-tracking.mdx index 2d40efb396..28de920dc6 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-5.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-5.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-5.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/_cluster-transaction-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_cluster-transaction-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_cluster-transaction-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_cluster-transaction-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-5.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-5.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-5.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/deleting-entities.mdx b/versioned_docs/version-5.1/client-api/session/deleting-entities.mdx index 81a7ebcb31..a4d0d7f124 100644 --- a/versioned_docs/version-5.1/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-5.1/client-api/session/how-to/check-if-attachment-exists.mdx index a87cd5c6dc..ac371e05a6 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-5.1/client-api/session/how-to/check-if-document-exists.mdx index f65fc256df..100f8f8655 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/check-if-document-exists.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-5.1/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-5.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-5.1/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-5.1/client-api/session/how-to/defer-operations.mdx index e126593869..dd839bc6af 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/defer-operations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-5.1/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-counters.mdx index fb07410a4f..f2e8f9e4bb 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-counters.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-5.1/client-api/session/how-to/ignore-entity-changes.mdx index ec0fea1629..d46a577949 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-5.1/client-api/session/how-to/perform-operations-lazily.mdx index 30eb401bc2..a21af5ffe5 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-5.1/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-5.1/client-api/session/how-to/subscribe-to-events.mdx index 590fa0e3b9..fab422008b 100644 --- a/versioned_docs/version-5.1/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-5.1/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/loading-entities.mdx b/versioned_docs/version-5.1/client-api/session/loading-entities.mdx index 2a39a6fb00..8214ff7506 100644 --- a/versioned_docs/version-5.1/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/opening-a-session.mdx b/versioned_docs/version-5.1/client-api/session/opening-a-session.mdx index 0b2921a7fa..bf2464701a 100644 --- a/versioned_docs/version-5.1/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-5.1/client-api/session/opening-a-session.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 90b70a1b8f..0000000000 --- a/versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# How to Filter by Non-Existing Field - - -* There are situations where over time new fields are added to documents. - You may need to create a list of all of the documents that don't have these fields. - * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) - to add the missing fields. - -* To find documents with a missing field you can either: - * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) - * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) - - - -## Query a Static Index - -You can search for documents with missing fields by using a static index if it indexes the field which is -suspected to be missing in some of the documents. - -The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. - -* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, - query an index that indexes the fields `Freight` and `Id`. -* If your static index does not contain the desired field, either - * Modify your index definition to index the specific field. (This will trigger re-indexing.) - * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). - -### Example: Query a Static Index - -In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. - -#### First we need an index that includes `Freight` and a field that exists in every document - -We index the missing field `Freight` and the field `Id`, which exists in every document. -This way, the index includes all of the documents in the collection, -including those that are missing the specified field. - - - -{`// Create or modify a static index called Orders_ByFreight -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public Orders_ByFreight() - \{ - // Specify collection name - Map = orders => from doc in orders - select new - \{ - // Field that is missing in some documents - doc.Freight, - // Field that exists in all documents - doc.Id - \}; - \} -\} -`} - - - -#### Then we query the index to find documents where the field does not exist - -SAMPLE QUERY: - -Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. - - - - -{`List results = session - .Advanced - // Query the static index - .DocumentQuery() - // Verify that the index is not stale (optional) - .WaitForNonStaleResults(TimeSpan.MaxValue) - // Negate the next method - .Not - // Specify the field that is suspected to be missing - .WhereExists(x => x.Freight) - .ToList(); - // \`results\` will contain the list of incomplete documents. -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - -LINQ SYNTAX: - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **TIndexCreator** | string | The name of the index that you want to use. | -| **missingFieldName**| string | The field that is missing in some of the documents. | - - - - -## Query the Collection to Create an Auto-Index - -Another option is to query the collection for the missing field. -This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. - -See the example and query syntax descriptions below: - -### Example: A query that creates an Auto-Index - -The following query will create an auto-index on the "Freight" field -that is missing in some documents in the Orders collection. -The query result will contain all documents that do not have this field. - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("Freight") - .ToList(); -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - -#### LINQ Query Syntax - - - -{`List results = session - .Advanced - .DocumentQuery() - .Not - .WhereExists("missingFieldName") - .ToList(); -`} - - - -| Parameters | Type | Description | -| -- | - | -- | -| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | -| **missingFieldName** | string | The field that is missing in some of the documents. | - - - - - -## Use Studio to filter by non-existing field - -You can also use Studio to find missing fields with an RQL query such as: - -``` -from "Orders" -where exists("Company") and not exists("Freight") -``` - -In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. -Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), -we must first call a field that exists in every document in the collection -and then the field that does not exist in some of them. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu items. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created for this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not have the specified field. - (The field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx deleted file mode 100644 index 17f9666668..0000000000 --- a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-csharp.mdx +++ /dev/null @@ -1,549 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of -spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, -and `OrderByDistanceDescending`. - -* In this page: - * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) - * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) - * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - - -## Spatial - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | - -### DynamicSpatialFieldFactory - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | -| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 miles radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - "Circle(32.1234 23.4321 d=10.0000)", - SpatialRelation.Within, - SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in index | -| **fieldName** | `string` | Path to spatial field in index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - -### Example II - -This example demonstrates rounding. The query sorts the results by distance from -the specified point, but rounds the distance up to the nearest 100 km interval. -All results within the same interval are sorted alphabetically by the field `Name`. - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = session - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToList(); -`} - - - - -{`// Return all entities and sort results by distance. -// Round the distance up to the nearest 100 km. -// Then sort alphabetically by the entity Name. -List results = await asyncSession - .Query() - .OrderByDistance( - factory => factory.Point( - x => x.Latitude, - x => x.Longitude) - .RoundTo(100), - 32.1234, - 23.4321) - .ThenBy(x => x.Name) - .ToListAsync(); -`} - - - - -{`from Houses as h -order by spatial.distance( - spatial.point(h.Latitude, h.Longitude), - spatial.point(32.1234, 23.4321), - 100), h.Name -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -| ------------- | ------------- | ----- | -| **path** | `Expression>` | Path to spatial field in an index | -| **fieldName** | `string` | Path to spatial field in an index | -| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToList(); -`} - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = await asyncSession - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) - .OrderByDistanceDescending( - factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) - .ToListAsync(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx deleted file mode 100644 index 9c5caf9969..0000000000 --- a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-a-spatial-index-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..68ea5e01e7 --- /dev/null +++ b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# How to Filter by Non-Existing Field + + +* There are situations where over time new fields are added to documents. + You may need to create a list of all of the documents that don't have these fields. + * You can then write a [patch](../../../client-api/operations/patching/set-based.mdx#update-by-static-index-query-result) + to add the missing fields. + +* To find documents with a missing field you can either: + * [Query a Static Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query the collection to create an Auto Index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index) + * [Use Studio to filter by non-existing field](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-filter-by-non-existing-field) + + + +## Query a Static Index + +You can search for documents with missing fields by using a static index if it indexes the field which is +suspected to be missing in some of the documents. + +The index definition must also index a field that exists in every document (such as `Id`) so that all documents will be indexed. + +* For example, if you want to find documents that are missing the field `Freight` in the `Orders` collection, + query an index that indexes the fields `Freight` and `Id`. +* If your static index does not contain the desired field, either + * Modify your index definition to index the specific field. (This will trigger re-indexing.) + * [Create an auto-index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-to-create-an-auto-index). + +### Example: Query a Static Index + +In our example, we are looking for documents that are missing the field `Freight` from the collection `Orders`. + +#### First we need an index that includes `Freight` and a field that exists in every document + +We index the missing field `Freight` and the field `Id`, which exists in every document. +This way, the index includes all of the documents in the collection, +including those that are missing the specified field. + + + +{`// Create or modify a static index called Orders_ByFreight +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public Orders_ByFreight() + \{ + // Specify collection name + Map = orders => from doc in orders + select new + \{ + // Field that is missing in some documents + doc.Freight, + // Field that exists in all documents + doc.Id + \}; + \} +\} +`} + + + +#### Then we query the index to find documents where the field does not exist + +SAMPLE QUERY: + +Query the index `Orders_ByFreight` and filter documents where `freight` does not exist. + + + + +{`List results = session + .Advanced + // Query the static index + .DocumentQuery() + // Verify that the index is not stale (optional) + .WaitForNonStaleResults(TimeSpan.MaxValue) + // Negate the next method + .Not + // Specify the field that is suspected to be missing + .WhereExists(x => x.Freight) + .ToList(); + // \`results\` will contain the list of incomplete documents. +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + +LINQ SYNTAX: + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **TIndexCreator** | string | The name of the index that you want to use. | +| **missingFieldName**| string | The field that is missing in some of the documents. | + + + + +## Query the Collection to Create an Auto-Index + +Another option is to query the collection for the missing field. +This will either create a new auto-index or add the new field to an existing auto-index if it indexes the same collection. + +See the example and query syntax descriptions below: + +### Example: A query that creates an Auto-Index + +The following query will create an auto-index on the "Freight" field +that is missing in some documents in the Orders collection. +The query result will contain all documents that do not have this field. + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("Freight") + .ToList(); +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + +#### LINQ Query Syntax + + + +{`List results = session + .Advanced + .DocumentQuery() + .Not + .WhereExists("missingFieldName") + .ToList(); +`} + + + +| Parameters | Type | Description | +| -- | - | -- | +| **T** | string | An object in a collection (singular of the collection name - e.g. Order from the collection Orders). | +| **missingFieldName** | string | The field that is missing in some of the documents. | + + + + + +## Use Studio to filter by non-existing field + +You can also use Studio to find missing fields with an RQL query such as: + +``` +from "Orders" +where exists("Company") and not exists("Freight") +``` + +In Studio we always use [RQL](../../../indexes/querying/what-is-rql.mdx) syntax. +Like the [LINQ syntax examples above](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index), +we must first call a field that exists in every document in the collection +and then the field that does not exist in some of them. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu items. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the query according to the [RQL example](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#example-a-query-that-creates-an-auto-index) described above. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created for this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not have the specified field. + (The field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-proximity-search-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-proximity-search-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-proximity-search-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-proximity-search-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-proximity-search-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx new file mode 100644 index 0000000000..f76839a4dc --- /dev/null +++ b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-csharp.mdx @@ -0,0 +1,549 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Spatial indexes can be queried using the `Spatial` method which contains a full spectrum of +spatial methods. The following article will cover the methods `Spatial()`, `OrderByDistance()`, +and `OrderByDistanceDescending`. + +* In this page: + * [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) + * [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) + * [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + + +## Spatial + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field from the `path` parameter. | + +### DynamicSpatialFieldFactory + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitudePath** or **longitudePath** or **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | `SpatialRelation` | Shape relation. Can be `Within`, `Contains`, `Disjoint`, `Intersects` | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | `double` | Used to define a radius circle | +| **radiusUnits** or **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles` | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 miles radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + "Circle(32.1234 23.4321 d=10.0000)", + SpatialRelation.Within, + SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)', 'Miles')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `OrderByDistance` method. The closest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in index | +| **fieldName** | `string` | Path to spatial field in index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The distance from the point is rounded up to the nearest interval. The results within the same interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [below](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + +### Example II + +This example demonstrates rounding. The query sorts the results by distance from +the specified point, but rounds the distance up to the nearest 100 km interval. +All results within the same interval are sorted alphabetically by the field `Name`. + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = session + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToList(); +`} + + + + +{`// Return all entities and sort results by distance. +// Round the distance up to the nearest 100 km. +// Then sort alphabetically by the entity Name. +List results = await asyncSession + .Query() + .OrderByDistance( + factory => factory.Point( + x => x.Latitude, + x => x.Longitude) + .RoundTo(100), + 32.1234, + 23.4321) + .ThenBy(x => x.Name) + .ToListAsync(); +`} + + + + +{`from Houses as h +order by spatial.distance( + spatial.point(h.Latitude, h.Longitude), + spatial.point(32.1234, 23.4321), + 100), h.Name +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +| ------------- | ------------- | ----- | +| **path** | `Expression>` | Path to spatial field in an index | +| **fieldName** | `string` | Path to spatial field in an index | +| **field** | `Func, DynamicSpatialField>` or `DynamicSpatialField` | Factory or field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | `string` | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers. The measured distance is rounded up to the nearest interval. The results within the same distance interval are then sorted by another order. This other order is the next [chained ordering](../../../indexes/querying/sorting.mdx#chaining-orderings), or if no other order was specified, then by ascending order of document Id. See example [above](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#example-ii-1). | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToList(); +`} + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = await asyncSession + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(10, 32.1234, 23.4321)) + .OrderByDistanceDescending( + factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321) + .ToListAsync(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234, 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx new file mode 100644 index 0000000000..2396725492 --- /dev/null +++ b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-a-spatial-index-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-query-a-spatial-index.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-query-with-exact-match-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-query-with-exact-match-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-fuzzy-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-fuzzy-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-fuzzy-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-fuzzy-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-fuzzy-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-highlighting-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-highlighting-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-highlighting-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-highlighting-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-highlighting-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-highlighting-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-regex-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-regex-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-use-search-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-use-search-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-use-search-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index a64e783cc2..0000000000 --- a/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery Timings(out QueryTimings timings); -`} - - - -## Example - - - - -{`var resultWithTimings = session.Advanced.DocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToList(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() - .Timings(out QueryTimings timings) - .Search(x => x.Name, "Syrup") - .ToListAsync(); - -IDictionary timingsDictionary = timings.Timings; -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index a85ad6f470..0000000000 --- a/versioned_docs/version-5.1/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQuery timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings-1.png) - diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..b777106c96 --- /dev/null +++ b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,57 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery Timings(out QueryTimings timings); +`} + + + +## Example + + + + +{`var resultWithTimings = session.Advanced.DocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToList(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`var resultWithTimings = await session.Advanced.AsyncDocumentQuery() + .Timings(out QueryTimings timings) + .Search(x => x.Name, "Syrup") + .ToListAsync(); + +IDictionary timingsDictionary = timings.Timings; +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..99f3fa91d6 --- /dev/null +++ b/versioned_docs/version-5.1/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQuery timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings-1.png) + diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/include-explanations.mdx index ec808ee6a9..4df35b7773 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/debugging/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-5.1/client-api/session/querying/debugging/query-timings.mdx index 945f73958f..7986688800 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/debugging/query-timings.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-5.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-5.1/client-api/session/querying/document-query/what-is-document-query.mdx index cef08c1c05..798546d402 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-customize-query.mdx index 2e9f4cd49b..d8110e41f3 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-field.mdx index f0ff8185c2..285ee08861 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 38b64f0c4f..d194cb8bcf 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-get-query-statistics.mdx index 83a9c90774..433e7bbfad 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 2671c19cf6..08c52105c3 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-proximity-search.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-proximity-search.mdx index ddaa663299..622e2335b3 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-proximity-search.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-proximity-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformProximitySearchCsharp from './_how-to-perform-proximity-search-csharp.mdx'; -import HowToPerformProximitySearchJava from './_how-to-perform-proximity-search-java.mdx'; +import HowToPerformProximitySearchCsharp from './content/_how-to-perform-proximity-search-csharp.mdx'; +import HowToPerformProximitySearchJava from './content/_how-to-perform-proximity-search-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-queries-lazily.mdx index e32d80e161..81bbc4fa19 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-project-query-results.mdx index 4064387648..9c7d07ff5c 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-query-a-spatial-index.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-query-a-spatial-index.mdx index a61668f911..2a328088f5 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-query-a-spatial-index.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-query-a-spatial-index.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryASpatialIndexCsharp from './_how-to-query-a-spatial-index-csharp.mdx'; -import HowToQueryASpatialIndexJava from './_how-to-query-a-spatial-index-java.mdx'; +import HowToQueryASpatialIndexCsharp from './content/_how-to-query-a-spatial-index-csharp.mdx'; +import HowToQueryASpatialIndexJava from './content/_how-to-query-a-spatial-index-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-query-with-exact-match.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-query-with-exact-match.mdx index 29dadbe6eb..c6befd9e24 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-query-with-exact-match.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-query-with-exact-match.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryWithExactMatchCsharp from './_how-to-query-with-exact-match-csharp.mdx'; -import HowToQueryWithExactMatchJava from './_how-to-query-with-exact-match-java.mdx'; -import HowToQueryWithExactMatchNodejs from './_how-to-query-with-exact-match-nodejs.mdx'; +import HowToQueryWithExactMatchCsharp from './content/_how-to-query-with-exact-match-csharp.mdx'; +import HowToQueryWithExactMatchJava from './content/_how-to-query-with-exact-match-java.mdx'; +import HowToQueryWithExactMatchNodejs from './content/_how-to-query-with-exact-match-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-query.mdx index 5338135aad..65f0860b27 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-fuzzy.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-fuzzy.mdx index 1b18017dcb..9d2276243c 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-fuzzy.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-fuzzy.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseFuzzyCsharp from './_how-to-use-fuzzy-csharp.mdx'; -import HowToUseFuzzyJava from './_how-to-use-fuzzy-java.mdx'; +import HowToUseFuzzyCsharp from './content/_how-to-use-fuzzy-csharp.mdx'; +import HowToUseFuzzyJava from './content/_how-to-use-fuzzy-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-highlighting.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-highlighting.mdx index 93ef8a0c20..a03a38aeea 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-highlighting.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseHighlightingCsharp from './_how-to-use-highlighting-csharp.mdx'; -import HowToUseHighlightingJava from './_how-to-use-highlighting-java.mdx'; +import HowToUseHighlightingCsharp from './content/_how-to-use-highlighting-csharp.mdx'; +import HowToUseHighlightingJava from './content/_how-to-use-highlighting-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-regex.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-regex.mdx index d46f82cab1..e0e9f41896 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-regex.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseRegexCsharp from './_how-to-use-regex-csharp.mdx'; -import HowToUseRegexJava from './_how-to-use-regex-java.mdx'; -import HowToUseRegexNodejs from './_how-to-use-regex-nodejs.mdx'; +import HowToUseRegexCsharp from './content/_how-to-use-regex-csharp.mdx'; +import HowToUseRegexJava from './content/_how-to-use-regex-java.mdx'; +import HowToUseRegexNodejs from './content/_how-to-use-regex-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-search.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-search.mdx index 8e128dfebb..eab93a36f4 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-use-search.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-use-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseSearchCsharp from './_how-to-use-search-csharp.mdx'; +import HowToUseSearchCsharp from './content/_how-to-use-search-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-5.1/client-api/session/querying/how-to-work-with-suggestions.mdx index dfc2413f17..c15846553c 100644 --- a/versioned_docs/version-5.1/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-5.1/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_counter-revisions-csharp.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_counter-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_counter-revisions-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_counter-revisions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_counter-revisions-java.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_counter-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_counter-revisions-java.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_counter-revisions-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-5.1/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/session/revisions/counter-revisions.mdx b/versioned_docs/version-5.1/client-api/session/revisions/counter-revisions.mdx index 2685ffaefe..096cb444a7 100644 --- a/versioned_docs/version-5.1/client-api/session/revisions/counter-revisions.mdx +++ b/versioned_docs/version-5.1/client-api/session/revisions/counter-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterRevisionsCsharp from './_counter-revisions-csharp.mdx'; -import CounterRevisionsJava from './_counter-revisions-java.mdx'; +import CounterRevisionsCsharp from './content/_counter-revisions-csharp.mdx'; +import CounterRevisionsJava from './content/_counter-revisions-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/revisions/loading.mdx b/versioned_docs/version-5.1/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-5.1/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-5.1/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-5.1/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-5.1/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-5.1/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/saving-changes.mdx b/versioned_docs/version-5.1/client-api/session/saving-changes.mdx index 3b7eb7ddb6..d56bf96c5d 100644 --- a/versioned_docs/version-5.1/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-5.1/client-api/session/saving-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/storing-entities.mdx b/versioned_docs/version-5.1/client-api/session/storing-entities.mdx index 09787c1800..dafb1abe29 100644 --- a/versioned_docs/version-5.1/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/updating-entities.mdx b/versioned_docs/version-5.1/client-api/session/updating-entities.mdx index c7a719d596..58a56a1004 100644 --- a/versioned_docs/version-5.1/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-5.1/client-api/session/updating-entities.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; diff --git a/versioned_docs/version-5.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-5.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx index 1eb9ad91cf..c17516971d 100644 --- a/versioned_docs/version-5.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-5.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; diff --git a/versioned_docs/version-5.1/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-5.1/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-5.1/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-5.1/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/setting-up-default-database.mdx b/versioned_docs/version-5.1/client-api/setting-up-default-database.mdx index 75fc4c2450..b217f301b3 100644 --- a/versioned_docs/version-5.1/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-5.1/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-5.1/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-5.1/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-5.1/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-5.1/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-5.1/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/client-api/what-is-a-document-store.mdx b/versioned_docs/version-5.1/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-5.1/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-5.1/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-5.1/document-extensions/attachments/copying-moving-renaming.mdx index b9774d0444..65484c9d78 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/deleting.mdx b/versioned_docs/version-5.1/document-extensions/attachments/deleting.mdx index 6259980cd3..3a916d6185 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/indexing.mdx b/versioned_docs/version-5.1/document-extensions/attachments/indexing.mdx index f85cb949d2..7f1a0fe446 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/loading.mdx b/versioned_docs/version-5.1/document-extensions/attachments/loading.mdx index 9df0597641..13d7ce3ad5 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/storing.mdx b/versioned_docs/version-5.1/document-extensions/attachments/storing.mdx index 63f3d6f602..f9646cbe1f 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-5.1/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-5.1/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-5.1/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-5.1/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-5.1/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-5.1/document-extensions/counters/counters-and-other-features.mdx index d567f37006..217b2590a4 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/counters-and-other-features.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-5.1/document-extensions/counters/create-or-modify.mdx index 5e8c29ec4a..8f8d71dfef 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/delete.mdx b/versioned_docs/version-5.1/document-extensions/counters/delete.mdx index 949fb2feed..d1e2ffe8a1 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/indexing.mdx b/versioned_docs/version-5.1/document-extensions/counters/indexing.mdx index 3631c6ba3a..fc79f90af0 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/overview.mdx b/versioned_docs/version-5.1/document-extensions/counters/overview.mdx index bf20ec9bcd..50c52e0ffe 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-5.1/document-extensions/counters/retrieve-counter-values.mdx index acd7025f97..669bcfbff9 100644 --- a/versioned_docs/version-5.1/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-5.1/document-extensions/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-5.1/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-5.1/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-5.1/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-5.1/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-5.1/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-5.1/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-5.1/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-5.1/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-5.1/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-5.1/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-5.1/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_index-query-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_index-query-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_query-result-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_query-result-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/_stream-result-csharp.mdx b/versioned_docs/version-5.1/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-5.1/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-5.1/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-5.1/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-5.1/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/counters-batch-command-data.mdx b/versioned_docs/version-5.1/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-5.1/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/delete-command-data.mdx b/versioned_docs/version-5.1/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-5.1/glossary/delete-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-5.1/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-5.1/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/index-query.mdx b/versioned_docs/version-5.1/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-5.1/glossary/index-query.mdx +++ b/versioned_docs/version-5.1/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/move-attachment-command-data.mdx b/versioned_docs/version-5.1/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-5.1/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/patch-command-data.mdx b/versioned_docs/version-5.1/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-5.1/glossary/patch-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/put-command-data.mdx b/versioned_docs/version-5.1/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-5.1/glossary/put-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-5.1/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-5.1/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.1/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/query-result.mdx b/versioned_docs/version-5.1/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-5.1/glossary/query-result.mdx +++ b/versioned_docs/version-5.1/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/stream-query-statistics.mdx b/versioned_docs/version-5.1/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-5.1/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-5.1/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-5.1/glossary/stream-result.mdx b/versioned_docs/version-5.1/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-5.1/glossary/stream-result.mdx +++ b/versioned_docs/version-5.1/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/_fanout-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/_fanout-indexes-csharp.mdx deleted file mode 100644 index 94f6065246..0000000000 --- a/versioned_docs/version-5.1/indexes/_fanout-indexes-csharp.mdx +++ /dev/null @@ -1,171 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public class Orders_ByProduct : AbstractIndexCreationTask -{ - public Orders_ByProduct() - { - Map = orders => from order in orders - from orderLine in order.Lines - select new - { - orderLine.Product, - orderLine.ProductName - }; - } -} -`} - - - - -{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByProduct() - { - Maps = new HashSet - { - @"map('Orders', function (order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - ProductName: l.ProductName - }) - }); - return res; - })", - }; - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public class Product_Sales : AbstractIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - public int Count { get; set; } - public decimal Total; - } - - public Product_Sales() - { - Map = orders => from order in orders - from line in order.Lines - select new Result - { - Product = line.Product, - Count = 1, - Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) - }; - - Reduce = results => from result in results - group result by result.Product - into g - select new - { - Product = g.Key, - Count = g.Sum(x => x.Count), - Total = g.Sum(x => x.Total) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.1/indexes/_fanout-indexes-java.mdx b/versioned_docs/version-5.1/indexes/_fanout-indexes-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-5.1/indexes/_fanout-indexes-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index a65d3ec381..0000000000 --- a/versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,206 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Use the indexing `Recurse` method to recurse through the layers of a hierarchical document -and index its elements. - -* In this Page: - * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) - - -## Hierarchical Data - -One of the significant advantages offered by document databases is their tendency not to force -limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: -take, for example, the commonly-used **Comment thread**, implemented using objects such as: - - -{`private class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Comments can be left recursively - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments -to its Comments field. And readers of these comments can reply with comments of their own, creating -a recursive hierarchical structure. - -`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of -comments left by various authors. - -`BlogPosts/1-A`: - - -{`\{ - "Author ": "John", - "Comments": [ - \{ - "Author": "Moon", - "Comments": [ - \{ - "Author": "Bob" - \}, - \{ - "Author": "Adel", - "Comments": \{ - "Author": "Moon" - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Indexing Hierarchical Data - -To index the elements of a hierarchical structure like the one demonstrated above, -use RavenDB's `Recurse` method. - -In the sample below, we use `Recurse` to go through comments in the post thread -and index them by their authors. - - - -{`private class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class Result - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new Result - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" - } - })); -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - return recurse(blogpost, x => x.Comments).map(function (comment) { - if (comment.Author != null) { - return { - Authors: comment.Author - }; - } - }); - });" - }; - } -} -`} - - - -### Querying the created index - -* The index we created can be queried using code. - - - -{`IList results = session - .Query() - .Where(x => x.Authors.Any(a => a == "John")) - .OfType() - .ToList(); -`} - - - - -{`IList results = session - .Advanced - .DocumentQuery() - .WhereEquals("Authors", "John") - .ToList(); -`} - - - - -* The index can also be queried using Studio. - - * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) - view to define and query the index. - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) - indexed by the `Recurse` method. - - !["Query View"](./assets/query-view.png) - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-5.1/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.1/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.1/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index e451c4cc90..0000000000 --- a/versioned_docs/version-5.1/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,337 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, __documents can reference other documents__. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition are tracked for changes. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents](../indexes/indexing-related-documents.mdx#index-related-documents) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a __Related Document__. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - -![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - - -#### Example I - basic -__What is tracked__: - -* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -__The documents__: - - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -__The index__: - -* This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done either on any document in the __indexed collection__ or in the __indexed related documents__ will trigger re-indexing. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.1/indexes/boosting.mdx b/versioned_docs/version-5.1/indexes/boosting.mdx index 63937b73b3..4e299192ad 100644 --- a/versioned_docs/version-5.1/indexes/boosting.mdx +++ b/versioned_docs/version-5.1/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/_boosting-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_boosting-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_boosting-java.mdx b/versioned_docs/version-5.1/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_boosting-java.mdx rename to versioned_docs/version-5.1/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_boosting-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_extending-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/content/_fanout-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_fanout-indexes-csharp.mdx new file mode 100644 index 0000000000..bb8d3382d9 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_fanout-indexes-csharp.mdx @@ -0,0 +1,171 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public class Orders_ByProduct : AbstractIndexCreationTask +{ + public Orders_ByProduct() + { + Map = orders => from order in orders + from orderLine in order.Lines + select new + { + orderLine.Product, + orderLine.ProductName + }; + } +} +`} + + + + +{`public class Orders_ByProduct : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByProduct() + { + Maps = new HashSet + { + @"map('Orders', function (order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + ProductName: l.ProductName + }) + }); + return res; + })", + }; + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public class Product_Sales : AbstractIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + public int Count { get; set; } + public decimal Total; + } + + public Product_Sales() + { + Map = orders => from order in orders + from line in order.Lines + select new Result + { + Product = line.Product, + Count = 1, + Total = ((line.Quantity*line.PricePerUnit)*(1 - line.Discount)) + }; + + Reduce = results => from result in results + group result by result.Product + into g + select new + { + Product = g.Key, + Count = g.Sum(x => x.Count), + Total = g.Sum(x => x.Total) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.1/indexes/content/_fanout-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_fanout-indexes-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_fanout-indexes-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.1/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-basics-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..185c74ef37 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,206 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Use the indexing `Recurse` method to recurse through the layers of a hierarchical document +and index its elements. + +* In this Page: + * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) + + +## Hierarchical Data + +One of the significant advantages offered by document databases is their tendency not to force +limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: +take, for example, the commonly-used **Comment thread**, implemented using objects such as: + + +{`private class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Comments can be left recursively + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments +to its Comments field. And readers of these comments can reply with comments of their own, creating +a recursive hierarchical structure. + +`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of +comments left by various authors. + +`BlogPosts/1-A`: + + +{`\{ + "Author ": "John", + "Comments": [ + \{ + "Author": "Moon", + "Comments": [ + \{ + "Author": "Bob" + \}, + \{ + "Author": "Adel", + "Comments": \{ + "Author": "Moon" + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Indexing Hierarchical Data + +To index the elements of a hierarchical structure like the one demonstrated above, +use RavenDB's `Recurse` method. + +In the sample below, we use `Recurse` to go through comments in the post thread +and index them by their authors. + + + +{`private class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class Result + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new Result + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" + } + })); +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + return recurse(blogpost, x => x.Comments).map(function (comment) { + if (comment.Author != null) { + return { + Authors: comment.Author + }; + } + }); + });" + }; + } +} +`} + + + +### Querying the created index + +* The index we created can be queried using code. + + + +{`IList results = session + .Query() + .Where(x => x.Authors.Any(a => a == "John")) + .OfType() + .ToList(); +`} + + + + +{`IList results = session + .Advanced + .DocumentQuery() + .WhereEquals("Authors", "John") + .ToList(); +`} + + + + +* The index can also be queried using Studio. + + * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) + view to define and query the index. + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) + indexed by the `Recurse` method. + + !["Query View"](../assets/query-view.png) + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-hierarchical-data-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-hierarchical-data-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.1/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..dcd37d49dd --- /dev/null +++ b/versioned_docs/version-5.1/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,337 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, __documents can reference other documents__. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition are tracked for changes. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents](../indexes/indexing-related-documents.mdx#index-related-documents) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a __Related Document__. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + +![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents + + +#### Example I - basic +__What is tracked__: + +* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +__The documents__: + + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +__The index__: + +* This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done either on any document in the __indexed collection__ or in the __indexed related documents__ will trigger re-indexing. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.1/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-related-documents-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-related-documents-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-related-documents-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-5.1/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-5.1/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-5.1/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-5.1/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_stale-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-5.1/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-5.1/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-analyzers-java.mdx b/versioned_docs/version-5.1/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-5.1/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-dynamic-fields-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-dynamic-fields-java.mdx rename to versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-dynamic-fields-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_using-dynamic-fields-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-5.1/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-5.1/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.1/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-5.1/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-5.1/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-5.1/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-5.1/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.1/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-5.1/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-5.1/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-5.1/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-5.1/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/creating-and-deploying.mdx b/versioned_docs/version-5.1/indexes/creating-and-deploying.mdx index ad82e6dc99..e0eebf6640 100644 --- a/versioned_docs/version-5.1/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-5.1/indexes/creating-and-deploying.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/extending-indexes.mdx b/versioned_docs/version-5.1/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-5.1/indexes/extending-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/fanout-indexes.mdx b/versioned_docs/version-5.1/indexes/fanout-indexes.mdx index c07252a661..c76c4ee85f 100644 --- a/versioned_docs/version-5.1/indexes/fanout-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/fanout-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FanoutIndexesCsharp from './_fanout-indexes-csharp.mdx'; -import FanoutIndexesJava from './_fanout-indexes-java.mdx'; +import FanoutIndexesCsharp from './content/_fanout-indexes-csharp.mdx'; +import FanoutIndexesJava from './content/_fanout-indexes-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-basics.mdx b/versioned_docs/version-5.1/indexes/indexing-basics.mdx index 72b153a25f..15560b37fc 100644 --- a/versioned_docs/version-5.1/indexes/indexing-basics.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-5.1/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-5.1/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-5.1/indexes/indexing-hierarchical-data.mdx index 8a19e0f1c3..c1b7998606 100644 --- a/versioned_docs/version-5.1/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-hierarchical-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-5.1/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-5.1/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-5.1/indexes/indexing-polymorphic-data.mdx index bddb362a3a..4c08de81be 100644 --- a/versioned_docs/version-5.1/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-related-documents.mdx b/versioned_docs/version-5.1/indexes/indexing-related-documents.mdx index c412fffe70..869df8c846 100644 --- a/versioned_docs/version-5.1/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-related-documents.mdx @@ -8,8 +8,8 @@ supported_languages: ["nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/indexing-spatial-data.mdx b/versioned_docs/version-5.1/indexes/indexing-spatial-data.mdx index 7f0511363d..caca7442e3 100644 --- a/versioned_docs/version-5.1/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-5.1/indexes/indexing-spatial-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/javascript-indexes.mdx b/versioned_docs/version-5.1/indexes/javascript-indexes.mdx index 7317155649..44909a2261 100644 --- a/versioned_docs/version-5.1/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/map-indexes.mdx b/versioned_docs/version-5.1/indexes/map-indexes.mdx index eda20d39b8..6627743621 100644 --- a/versioned_docs/version-5.1/indexes/map-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/map-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/map-reduce-indexes.mdx b/versioned_docs/version-5.1/indexes/map-reduce-indexes.mdx index 016c413f89..12e84e1c0a 100644 --- a/versioned_docs/version-5.1/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/map-reduce-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/multi-map-indexes.mdx b/versioned_docs/version-5.1/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-5.1/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/number-type-conversion.mdx b/versioned_docs/version-5.1/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-5.1/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-5.1/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index dfeeef4291..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search_2.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera -\{ - public DateTime DateOfListing \{ get; set; \} - - public string Model \{ get; set; \} - - public decimal Cost \{ get; set; \} - - public int Zoom \{ get; set; \} - - public double Megapixels \{ get; set; \} - - public bool ImageStabilizer \{ get; set; \} - - public string Manufacturer \{ get; set; \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask -\{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() - \{ - Map = cameras => from camera in cameras - select new - \{ - camera.Manufacturer, - camera.Model, - camera.Cost, - camera.DateOfListing, - camera.Megapixels - \}; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`List facets = new List -\{ - new Facet - \{ - FieldName = "Manufacturer" - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - \} - \}, - new RangeFacet - \{ - Ranges = - \{ - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - \} - \} -\}; -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **Cost** field, return the count of the following ranges: - - * Cost < 200.0 - * 200.0 <= Cost < 400.0 - * 400.0 <= Cost < 600.0 - * 600.0 <= Cost < 800.0 - * Cost >= 800.0 -* For the **Megapixels** field, return the count of the following ranges: - * Megapixels <= 3.0 - * 3.0 <= Megapixels < 7.0 - * 7.0 <= Megapixels < 10.0 - * Megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateBy(facets) - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(Manufacturer), - facet(Cost <= 200, - Cost between 200 and 400, - Cost between 400 and 600, Cost between 600 and 800, - Cost >= 800), - facet(Megapixels <= 3, - Megapixels between 3 and 7, - Megapixels between 7 and 10, - Megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "Manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "Cost", - "Values": [ - \{ - "Count": 6, - "Range": "Cost <= 200" - \}, - \{ - "Count": 2, - "Range": "Cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "Cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "Cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "Cost >= 800" - \} - ] - \}, - \{ - "Name": "Megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "Megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "Megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "Megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "Megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); -`} - - - - - - -{`Dictionary facetResults = session - .Query() - .Where(x => x.Cost >= 100 && x.Cost <= 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`Dictionary facetResults = session - .Advanced - .DocumentQuery() - .WhereBetween(x => x.Cost, 100, 300) - .AggregateUsing("facets/CameraFacets") - .Execute(); -`} - - - - -{`List facets = new List -{ - new Facet - { - FieldName = "Manufacturer" - }, - new RangeFacet - { - Ranges = - { - camera => camera.Cost < 200m, - camera => camera.Cost >= 200m && camera.Cost < 400m, - camera => camera.Cost >= 400m && camera.Cost < 600m, - camera => camera.Cost >= 600m && camera.Cost < 800m, - camera => camera.Cost >= 800m - } - }, - new RangeFacet - { - Ranges = - { - camera => camera.Megapixels < 3.0, - camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, - camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, - camera => camera.Megapixels >= 10.0 - } - } -}; -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where Cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-5.1/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ecb4312302..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.1/indexes/querying/_paging-java.mdx b/versioned_docs/version-5.1/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.1/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index e52c0cff7a..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a Fanout index. - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.1/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/_spatial-csharp.mdx deleted file mode 100644 index b8e29cae09..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_spatial-csharp.mdx +++ /dev/null @@ -1,165 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `RelatesToShape` - - - - -{`List results = session - .Query() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - factory => factory.Point(x => x.Latitude, x => x.Longitude), - criteria => criteria.RelatesToShape( - shapeWkt: "Circle(30 30 d=500.0000)", - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .Query() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .Spatial( - "Coordinates", - criteria => criteria.WithinRadius(500, 30, 30)) - .ToList(); -`} - - - - -{`public class Events_ByCoordinates : AbstractIndexCreationTask -{ - public Events_ByCoordinates() - { - Map = events => from e in events - select new - { - Coordinates = CreateSpatialField(e.Latitude, e.Longitude) - }; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(Coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.1/indexes/querying/_spatial-java.mdx b/versioned_docs/version-5.1/indexes/querying/_spatial-java.mdx deleted file mode 100644 index 052325a8dc..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.1/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/_spatial-nodejs.mdx deleted file mode 100644 index 77542032c5..0000000000 --- a/versioned_docs/version-5.1/indexes/querying/_spatial-nodejs.mdx +++ /dev/null @@ -1,122 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape()` - - - - -{`const results = await session - .query(Event) - .spatial(new PointField("latitude", "longitude"), - criteria => criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - "Within" - )) - .all(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL Database - How to Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`const results = await session - .query({ indexName: "Events/ByCoordinates" }) - .spatial("coordinates", - criteria => criteria.withinRadius(500, 30, 30)) - .all(); -`} - - - - -{`class Events_ByCoordinates extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Events.Select(e => new { - Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) - })\`; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.1/indexes/querying/basics.mdx b/versioned_docs/version-5.1/indexes/querying/basics.mdx index f1cbf38302..23f7507680 100644 --- a/versioned_docs/version-5.1/indexes/querying/basics.mdx +++ b/versioned_docs/version-5.1/indexes/querying/basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BasicsCsharp from './_basics-csharp.mdx'; -import BasicsJava from './_basics-java.mdx'; -import BasicsNodejs from './_basics-nodejs.mdx'; +import BasicsCsharp from './content/_basics-csharp.mdx'; +import BasicsJava from './content/_basics-java.mdx'; +import BasicsNodejs from './content/_basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/boosting.mdx b/versioned_docs/version-5.1/indexes/querying/boosting.mdx index 97dc2a028f..35a0a0b712 100644 --- a/versioned_docs/version-5.1/indexes/querying/boosting.mdx +++ b/versioned_docs/version-5.1/indexes/querying/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/_basics-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_basics-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_basics-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_basics-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_basics-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_basics-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_basics-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_basics-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_basics-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_basics-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_boosting-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_boosting-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_boosting-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_boosting-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_boosting-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_boosting-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_distinct-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..beb2d2de99 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search_2.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera +\{ + public DateTime DateOfListing \{ get; set; \} + + public string Model \{ get; set; \} + + public decimal Cost \{ get; set; \} + + public int Zoom \{ get; set; \} + + public double Megapixels \{ get; set; \} + + public bool ImageStabilizer \{ get; set; \} + + public string Manufacturer \{ get; set; \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels : AbstractIndexCreationTask +\{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() + \{ + Map = cameras => from camera in cameras + select new + \{ + camera.Manufacturer, + camera.Model, + camera.Cost, + camera.DateOfListing, + camera.Megapixels + \}; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`List facets = new List +\{ + new Facet + \{ + FieldName = "Manufacturer" + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + \} + \}, + new RangeFacet + \{ + Ranges = + \{ + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + \} + \} +\}; +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **Manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **Cost** field, return the count of the following ranges: + + * Cost < 200.0 + * 200.0 <= Cost < 400.0 + * 400.0 <= Cost < 600.0 + * 600.0 <= Cost < 800.0 + * Cost >= 800.0 +* For the **Megapixels** field, return the count of the following ranges: + * Megapixels <= 3.0 + * 3.0 <= Megapixels < 7.0 + * 7.0 <= Megapixels < 10.0 + * Megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateBy(facets) + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(Manufacturer), + facet(Cost <= 200, + Cost between 200 and 400, + Cost between 400 and 600, Cost between 600 and 800, + Cost >= 800), + facet(Megapixels <= 3, + Megapixels between 3 and 7, + Megapixels between 7 and 10, + Megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "Manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "Cost", + "Values": [ + \{ + "Count": 6, + "Range": "Cost <= 200" + \}, + \{ + "Count": 2, + "Range": "Cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "Cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "Cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "Cost >= 800" + \} + ] + \}, + \{ + "Name": "Megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "Megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "Megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "Megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "Megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`session.Store(new FacetSetup \{ Id = "facets/CameraFacets", Facets = facets, RangeFacets = rangeFacets \}); +`} + + + + + + +{`Dictionary facetResults = session + .Query() + .Where(x => x.Cost >= 100 && x.Cost <= 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`Dictionary facetResults = session + .Advanced + .DocumentQuery() + .WhereBetween(x => x.Cost, 100, 300) + .AggregateUsing("facets/CameraFacets") + .Execute(); +`} + + + + +{`List facets = new List +{ + new Facet + { + FieldName = "Manufacturer" + }, + new RangeFacet + { + Ranges = + { + camera => camera.Cost < 200m, + camera => camera.Cost >= 200m && camera.Cost < 400m, + camera => camera.Cost >= 400m && camera.Cost < 600m, + camera => camera.Cost >= 600m && camera.Cost < 800m, + camera => camera.Cost >= 800m + } + }, + new RangeFacet + { + Ranges = + { + camera => camera.Megapixels < 3.0, + camera => camera.Megapixels >= 3.0 && camera.Megapixels < 7.0, + camera => camera.Megapixels >= 7.0 && camera.Megapixels < 10.0, + camera => camera.Megapixels >= 10.0 + } + } +}; +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where Cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `WaitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `AggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-5.1/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_filtering-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_intersection-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..967fb68620 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/fanout-indexes.mdx). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.1/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.1/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2cc2e022a --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a Fanout index. + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.1/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_projections-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_projections-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_sorting-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/content/_spatial-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_spatial-csharp.mdx new file mode 100644 index 0000000000..1062993808 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_spatial-csharp.mdx @@ -0,0 +1,165 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `Spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `WithinRadius` method. + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `RelatesToShape` + + + + +{`List results = session + .Query() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + factory => factory.Point(x => x.Latitude, x => x.Longitude), + criteria => criteria.RelatesToShape( + shapeWkt: "Circle(30 30 d=500.0000)", + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `Within`, `Contains`, `Disjoint`, `Intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .Query() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .Spatial( + "Coordinates", + criteria => criteria.WithinRadius(500, 30, 30)) + .ToList(); +`} + + + + +{`public class Events_ByCoordinates : AbstractIndexCreationTask +{ + public Events_ByCoordinates() + { + Map = events => from e in events + select new + { + Coordinates = CreateSpatialField(e.Latitude, e.Longitude) + }; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(Coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `OrderByDistance` or `OrderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.1/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..9c11a03099 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.1/indexes/querying/content/_spatial-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_spatial-nodejs.mdx new file mode 100644 index 0000000000..9e318daef2 --- /dev/null +++ b/versioned_docs/version-5.1/indexes/querying/content/_spatial-nodejs.mdx @@ -0,0 +1,122 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial()` method which contains a full spectrum of spatial capabilities. You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius()` method. + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape()` + + + + +{`const results = await session + .query(Event) + .spatial(new PointField("latitude", "longitude"), + criteria => criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + "Within" + )) + .all(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL Database - How to Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`const results = await session + .query({ indexName: "Events/ByCoordinates" }) + .spatial("coordinates", + criteria => criteria.withinRadius(500, 30, 30)) + .all(); +`} + + + + +{`class Events_ByCoordinates extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Events.Select(e => new { + Coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) + })\`; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance()` or `orderByDistanceDescending()` methods. You can read more about them [here](../../client-api/session/querying/how-to-query-a-spatial-index.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.1/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-5.1/indexes/querying/content/_suggestions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_suggestions-csharp.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_suggestions-csharp.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-5.1/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-5.1/indexes/querying/content/_suggestions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.1/indexes/querying/_suggestions-nodejs.mdx rename to versioned_docs/version-5.1/indexes/querying/content/_suggestions-nodejs.mdx diff --git a/versioned_docs/version-5.1/indexes/querying/distinct.mdx b/versioned_docs/version-5.1/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-5.1/indexes/querying/distinct.mdx +++ b/versioned_docs/version-5.1/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/faceted-search.mdx b/versioned_docs/version-5.1/indexes/querying/faceted-search.mdx index 2886577ee1..427d2f26d2 100644 --- a/versioned_docs/version-5.1/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-5.1/indexes/querying/faceted-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/filtering.mdx b/versioned_docs/version-5.1/indexes/querying/filtering.mdx index c1c3bf3139..ba11c389e5 100644 --- a/versioned_docs/version-5.1/indexes/querying/filtering.mdx +++ b/versioned_docs/version-5.1/indexes/querying/filtering.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/highlighting.mdx b/versioned_docs/version-5.1/indexes/querying/highlighting.mdx index caddfb8b7c..98d011b0fb 100644 --- a/versioned_docs/version-5.1/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-5.1/indexes/querying/highlighting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/intersection.mdx b/versioned_docs/version-5.1/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-5.1/indexes/querying/intersection.mdx +++ b/versioned_docs/version-5.1/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/morelikethis.mdx b/versioned_docs/version-5.1/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-5.1/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-5.1/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/paging.mdx b/versioned_docs/version-5.1/indexes/querying/paging.mdx index 4a4f877127..1375a3d67e 100644 --- a/versioned_docs/version-5.1/indexes/querying/paging.mdx +++ b/versioned_docs/version-5.1/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/projections.mdx b/versioned_docs/version-5.1/indexes/querying/projections.mdx index f358bb4489..84724cf411 100644 --- a/versioned_docs/version-5.1/indexes/querying/projections.mdx +++ b/versioned_docs/version-5.1/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/query-vs-document-query.mdx b/versioned_docs/version-5.1/indexes/querying/query-vs-document-query.mdx index b766203269..8d99869330 100644 --- a/versioned_docs/version-5.1/indexes/querying/query-vs-document-query.mdx +++ b/versioned_docs/version-5.1/indexes/querying/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/searching.mdx b/versioned_docs/version-5.1/indexes/querying/searching.mdx index 2f747d4661..fb4145a63d 100644 --- a/versioned_docs/version-5.1/indexes/querying/searching.mdx +++ b/versioned_docs/version-5.1/indexes/querying/searching.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/sorting.mdx b/versioned_docs/version-5.1/indexes/querying/sorting.mdx index a230093906..fc72ce4f44 100644 --- a/versioned_docs/version-5.1/indexes/querying/sorting.mdx +++ b/versioned_docs/version-5.1/indexes/querying/sorting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/spatial.mdx b/versioned_docs/version-5.1/indexes/querying/spatial.mdx index 1e4e0092b9..5df771eb7a 100644 --- a/versioned_docs/version-5.1/indexes/querying/spatial.mdx +++ b/versioned_docs/version-5.1/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialJava from './_spatial-java.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/querying/suggestions.mdx b/versioned_docs/version-5.1/indexes/querying/suggestions.mdx index 8e46c2ed39..d5209e47da 100644 --- a/versioned_docs/version-5.1/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-5.1/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/sorting-and-collation.mdx b/versioned_docs/version-5.1/indexes/sorting-and-collation.mdx index c55cbb45c0..f3c27ca9c0 100644 --- a/versioned_docs/version-5.1/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-5.1/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-5.1/indexes/stale-indexes.mdx b/versioned_docs/version-5.1/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-5.1/indexes/stale-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/storing-data-in-index.mdx b/versioned_docs/version-5.1/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-5.1/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-5.1/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/using-analyzers.mdx b/versioned_docs/version-5.1/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-5.1/indexes/using-analyzers.mdx +++ b/versioned_docs/version-5.1/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/using-dynamic-fields.mdx b/versioned_docs/version-5.1/indexes/using-dynamic-fields.mdx index ee3eaf7804..570965a08c 100644 --- a/versioned_docs/version-5.1/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-5.1/indexes/using-dynamic-fields.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/using-term-vectors.mdx b/versioned_docs/version-5.1/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-5.1/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-5.1/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/indexes/what-are-indexes.mdx b/versioned_docs/version-5.1/indexes/what-are-indexes.mdx index baeb219b47..613babe12e 100644 --- a/versioned_docs/version-5.1/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-5.1/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.1/server/_embedded-csharp.mdx b/versioned_docs/version-5.1/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/server/_embedded-csharp.mdx rename to versioned_docs/version-5.1/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-5.1/server/_embedded-java.mdx b/versioned_docs/version-5.1/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-5.1/server/_embedded-java.mdx rename to versioned_docs/version-5.1/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-5.1/server/embedded.mdx b/versioned_docs/version-5.1/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-5.1/server/embedded.mdx +++ b/versioned_docs/version-5.1/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-5.1/start/_test-driver-csharp.mdx b/versioned_docs/version-5.1/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.1/start/_test-driver-csharp.mdx rename to versioned_docs/version-5.1/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-5.1/start/_test-driver-java.mdx b/versioned_docs/version-5.1/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-5.1/start/_test-driver-java.mdx rename to versioned_docs/version-5.1/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-5.1/start/test-driver.mdx b/versioned_docs/version-5.1/start/test-driver.mdx index caaf54ab4c..76d2299c77 100644 --- a/versioned_docs/version-5.1/start/test-driver.mdx +++ b/versioned_docs/version-5.1/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-5.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-5.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-5.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-5.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-5.2/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-5.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-5.2/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-5.2/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-5.2/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-5.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-5.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-5.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-5.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-5.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-5.2/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-5.2/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-5.2/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-5.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-5.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-5.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-5.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-5.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-5.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-5.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-5.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 3fbea43e2e..eaccf2717d 100644 --- a/versioned_docs/version-5.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-5.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-5.2/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/delete.mdx b/versioned_docs/version-5.2/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-5.2/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-5.2/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/commands/documents/get.mdx b/versioned_docs/version-5.2/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-5.2/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-5.2/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-5.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-5.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-5.2/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-5.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-5.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-5.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-5.2/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/commands/documents/put.mdx b/versioned_docs/version-5.2/client-api/commands/documents/put.mdx index 1178a97257..016c1f2cb7 100644 --- a/versioned_docs/version-5.2/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-5.2/client-api/commands/documents/put.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_querying-java.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-5.2/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-5.2/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/conventions.mdx b/versioned_docs/version-5.2/client-api/configuration/conventions.mdx index dfa17b75ef..c53640c457 100644 --- a/versioned_docs/version-5.2/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/conventions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/deserialization.mdx b/versioned_docs/version-5.2/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-5.2/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-5.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-5.2/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.2/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-5.2/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.2/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/load-balance-behavior.mdx index c362cda8f6..da0fb2a1ac 100644 --- a/versioned_docs/version-5.2/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-5.2/client-api/configuration/load-balance/read-balance-behavior.mdx index 269c259de1..5605fa9f14 100644 --- a/versioned_docs/version-5.2/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/querying.mdx b/versioned_docs/version-5.2/client-api/configuration/querying.mdx index eddc8e8e0e..b099c78cfd 100644 --- a/versioned_docs/version-5.2/client-api/configuration/querying.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/configuration/serialization.mdx b/versioned_docs/version-5.2/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-5.2/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-5.2/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-5.2/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-5.2/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/_creating-document-store-java.mdx b/versioned_docs/version-5.2/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-5.2/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-5.2/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-5.2/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-5.2/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-5.2/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-5.2/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-5.2/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-5.2/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-5.2/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-5.2/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-5.2/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/creating-document-store.mdx b/versioned_docs/version-5.2/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-5.2/client-api/creating-document-store.mdx +++ b/versioned_docs/version-5.2/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index 139fb6d129..0000000000 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index bcc4e2cb1f..0000000000 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 0d65f652f9..0000000000 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -In this page: -[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) -[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) -[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) -[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) -[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) -[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) -[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index 545845e219..b9549d42f0 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d296754727..46beae2231 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 0ebc8ffa28..a7c47c814e 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..769973c3a7 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,130 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..51b64ce7ed --- /dev/null +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..4f7017687b --- /dev/null +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +In this page: +[Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) +[What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) +[Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) +[Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) +[How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) +[Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) +[Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/api-overview.mdx index 460655150d..e05c87edf4 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-5.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/examples.mdx index ca8c2f97c2..d5c631951d 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/examples.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-5.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-5.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-5.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-5.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-5.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-5.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-5.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-5.2/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-5.2/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-5.2/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-5.2/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-5.2/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-5.2/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-5.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-5.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-5.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-5.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-5.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-5.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-5.2/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-5.2/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-5.2/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-5.2/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-5.2/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-5.2/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-5.2/client-api/how-to/handle-document-relationships.mdx index 6841264687..76ed44de53 100644 --- a/versioned_docs/version-5.2/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-5.2/client-api/how-to/handle-document-relationships.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-5.2/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-5.2/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-5.2/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-5.2/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-5.2/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-5.2/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/net-client-versions.mdx b/versioned_docs/version-5.2/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-5.2/client-api/net-client-versions.mdx +++ b/versioned_docs/version-5.2/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-5.2/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-5.2/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-5.2/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-5.2/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-5.2/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-5.2/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-5.2/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-5.2/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-5.2/client-api/operations/common/delete-by-query.mdx index 40c0818ab2..331c375620 100644 --- a/versioned_docs/version-5.2/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-5.2/client-api/operations/common/delete-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-5.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 8eb75698fb..e5de026d99 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index b05dd86c51..0922b9c087 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/include-compare-exchange.mdx index 504daa4a02..0e3e24afd7 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/overview.mdx index 8c80839bba..2b4ce01f23 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-5.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-5.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-5.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-5.2/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-5.2/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-5.2/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-5.2/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-5.2/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-5.2/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-5.2/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-5.2/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-5.2/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-5.2/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index d98c4cb72b..427c80ccc5 100644 --- a/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index cbc3247c96..618b398e0b 100644 --- a/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-5.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 241803adef..ff1a46ab8e 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 76fab69461..4e12d9bf02 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 13391da1a9..8d99d80a54 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index dbbb74bb3e..81f30c05e4 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 8870c1da85..418075a390 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 715c28bc20..e48caa5360 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/add-etl.mdx index 8d33194ade..5467e65ce6 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/get-stats.mdx index 2af9e8b305..9a5eb0560d 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/get-stats.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/get-identities.mdx index b4830fe5bd..f269c0e388 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3e8e9f64cb..f17cb462b1 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/seed-identity.mdx index d6780f54f4..7252a96b13 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 4930f0eb79..0961e85a1b 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index.mdx index 1bcd463a4c..3573589211 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/disable-index.mdx index bde3442b40..ed170f520d 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/enable-index.mdx index 5f0de84e7d..b30e75cbe4 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-errors.mdx index 34761e492b..c4fd99dd69 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-names.mdx index 8d3f50cf6a..9c89cbd2af 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index.mdx index 5dec14fb05..6c48d78278 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-indexes.mdx index 61fdba459f..4a205ceff2 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-terms.mdx index dcdb592ca0..48b840a4a5 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/index-has-changed.mdx index ab3eb1b945..5d85b4fe57 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/put-indexes.mdx index c691b6b356..933fb3115f 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/reset-index.mdx index cc7a1b38e9..533f2a88e9 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-lock.mdx index c148cdc2eb..2d273d3a1c 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-priority.mdx index 4a04c5b204..cdc3320965 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-index.mdx index 4c35b6487b..58198fc92a 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-indexing.mdx index c1cea19f21..400bb702ac 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-index.mdx index c01fe0836b..0cd435f749 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-indexing.mdx index befca12644..0b4aa4a308 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-5.2/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-5.2/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-5.2/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/patching/set-based.mdx b/versioned_docs/version-5.2/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-5.2/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-5.2/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/patching/single-document.mdx b/versioned_docs/version-5.2/client-api/operations/patching/single-document.mdx index 6dc6e75272..b41b31d73b 100644 --- a/versioned_docs/version-5.2/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-5.2/client-api/operations/patching/single-document.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/revisions/configure-revisions.mdx b/versioned_docs/version-5.2/client-api/operations/revisions/configure-revisions.mdx index 54470ca110..09a3f0e967 100644 --- a/versioned_docs/version-5.2/client-api/operations/revisions/configure-revisions.mdx +++ b/versioned_docs/version-5.2/client-api/operations/revisions/configure-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/revisions/_configure-revisions-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/revisions/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/revisions/_configure-revisions-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/revisions/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/revisions/_configure-revisions-java.mdx b/versioned_docs/version-5.2/client-api/operations/revisions/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/revisions/_configure-revisions-java.mdx rename to versioned_docs/version-5.2/client-api/operations/revisions/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/add-database-node.mdx index 173aaebd50..0e2b6b7fc6 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/add-database-node.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/compact-database.mdx index 1da4f1b4dc..90b8264f2e 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/compact-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/create-database.mdx index fb3313d4b2..01e457774f 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-5.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-databases-state.mdx index d1d01a84a6..5fd1ae5a24 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-5.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/operations/what-are-operations.mdx b/versioned_docs/version-5.2/client-api/operations/what-are-operations.mdx index 2c0688e09d..80544bf561 100644 --- a/versioned_docs/version-5.2/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-5.2/client-api/operations/what-are-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-5.2/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-5.2/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/security/deserialization-security.mdx b/versioned_docs/version-5.2/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-5.2/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-5.2/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index a21600f0c9..0000000000 --- a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,191 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) - key/value items that RavenDB creates and manages automatically to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) - transactions in cluster-wide sessions. - Each document will be associated with its own unique Atomic-Guard item. - -* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. - Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, - which is triggered by changing the document. - -* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to - administer compare-exchange entries explicitly. You can still do that if you wish by - [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - the automatic usage of atomic-guards in a session and defining and managing compare exchange - key/value pairs - [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) - where needed. - * **We strongly recommend not managing atomic-guards manually** unless you _truly_ know what you're doing. - Doing so could cancel RavenDB's ACID transaction guarantees. - -* In this page: - * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) - * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) - * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) - * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - - -## How Atomic Guards Work - -Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. -The Atomic-Guards are managed as follows: - -* __New document__: - A new Atomic-Guard is created when successfully saving a new document. - -* __Existing document that doesn't have an Atomic-Guard__: - A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. - -* __Existing document that already has an Atomic-Guard__: - - * Whenever one session modifies a document that already has an associated Atomic-Guard, - the value of its related Atomic-Guard increases. - This allows RavenDB to detect that changes were made to this document. - - * If other sessions have loaded the document before the version changed, - they will not be able to modify it if trying to save after the first session already saved it, - and a `ConcurrencyException` will be thrown. - - * If the session `SaveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. - Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. - - - -## Atomic Guard Transaction Scope - -* Atomic-Guards are local to the database they were defined on. - -* Since Atomic-Guards are implemented as compare-exchange items, - they are Not externally replicated to another database by any ongoing replication task. - Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Syntax and Usage - -In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, -and then used when two sessions compete on changing the document. - - - -{`using (var session = store.OpenAsyncSession(new SessionOptions - \{ - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - \})) -\{ - await session.StoreAsync(new User(), "users/johndoe"); - await session.SaveChangesAsync(); - // An atomic-guard is now automatically created for the new document "users/johndoe". -\} - -// Open two more cluster-wide sessions -using (var session1 = store.OpenAsyncSession( - new SessionOptions - \{TransactionMode = TransactionMode.ClusterWide\})) -using (var session2 = store.OpenAsyncSession( - new SessionOptions - \{TransactionMode = TransactionMode.ClusterWide\})) -\{ - // The two sessions will load the same document at the same time - var loadedUser1 = await session1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await session2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // Session1 will save changes first, which triggers a change in the - // version number of the associated atomic-guard. - await session1.SaveChangesAsync(); - - // session2.saveChanges() will be rejected with ConcurrencyException - // since session1 already changed the atomic-guard version, - // and session2 saveChanges uses the document version that it had when it loaded the document. - await session2.SaveChangesAsync(); -\} -`} - - - -After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, -in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -The generated Atomic-Guard key name is composed of: - - * The prefix `rvn-atomic` - * The ID of the document that it is associated with - - - -## Disabling Atomic Guards - -To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session -`DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - -In the sample below, the session uses **no Atomic-Guards**. - - -{`using (var session = store.OpenAsyncSession(new SessionOptions - \{ - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - \})) -\{ - await session.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await session.SaveChangesAsync(); -\} -`} - - - - - -* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, - you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) - the required compare exchange key/value pairs. - -* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively - impact ACID transaction guarantees. - -* **Do not remove or edit** Atomic-Guards manually while a session is using them. - A session that is currently using these removed Atomic-Guards will not be able to save - their related documents resulting in an error. - * If you accidentally remove an active Atomic-Guard that is associated with an existing document, - recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. - - - - -## When are Atomic Guards Removed - -Atomic guards expire on the expiration of the documents they are used for and are automatically -removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. - - -Since different cleanup tasks handle the removal of deleted and expired documents -and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed -documents would linger in the compare exchange entries list a short while longer before -they are removed. - -* You do **not** need to remove such Atomic-Guards yourself, they will be removed by - the cleanup task. -* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. - RavenDB will create new Atomic-Guards for such documents, and expire the old ones. - - - - - diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index c3348137ff..0000000000 --- a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,192 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) - key/value items that RavenDB creates and manages automatically to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) - transactions in cluster-wide sessions. - Each document will be associated with its own unique Atomic-Guard item. - -* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. - Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, - which is triggered by changing the document. - -* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to - administer compare-exchange entries explicitly. You can still do that if you wish by - [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - the automatic usage of Atomic-Guards in a session and defining and managing compare exchange - key/value pairs - [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) - where needed. - * **We strongly recommend not managing Atomic-Guards manually** unless you _truly_ know what you're doing. - Doing so could cancel RavenDB's ACID transaction guarantees. - -* In this page: - * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) - * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) - * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) - * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - - -## How Atomic Guards Work - -Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. -The Atomic-Guards are managed as follows: - -* __New document__: - A new Atomic-Guard is created when successfully saving a new document. - -* __Existing document that doesn't have an Atomic-Guard__: - A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. - -* __Existing document that already has an Atomic-Guard__: - - * Whenever one session modifies a document that already has an associated Atomic-Guard, - the value of its related Atomic-Guard increases. - This allows RavenDB to detect that changes were made to this document. - - * If other sessions have loaded the document before the version changed, - they will not be able to modify it if trying to save after the first session already saved it, - and a `ConcurrencyException` will be thrown. - - * If the session `saveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. - Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. - - - -## Atomic Guard Transaction Scope - -* Atomic-Guards are local to the database they were defined on. - -* Since Atomic-Guards are implemented as compare-exchange items, - they are Not externally replicated to another database by any ongoing replication task. - Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Syntax and Usage - -In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, -and then used when two sessions compete on changing the document. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two more cluster-wide sessions -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// The two sessions will load the same document at the same time -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 will save changes first, which triggers a change in the -// version number of the associated atomic-guard. -await session1.saveChanges(); - -// session2.saveChanges() will be rejected with a ClusterTransactionConcurrencyException -// since session1 already changed the atomic-guard version, -// and session2 saveChanges uses the document version that it had when it loaded the document. -await session2.saveChanges(); -`} - - - -After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, -in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -The generated Atomic-Guard key name is composed of: - -* The prefix `rvn-atomic` -* The ID of the document that it is associated with - - - -## Disabling Atomic Guards - -To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session -`disableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - -In the sample below, the session uses **no Atomic-Guards**. - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, - you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) - the required compare exchange key/value pairs. - -* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively - impact ACID transaction guarantees. - -* **Do not remove or edit** Atomic-Guards manually while a session is using them. - A session that is currently using these removed Atomic-Guards will not be able to save - their related documents resulting in an error. - * If you accidentally remove an active Atomic-Guard that is associated with an existing document, - recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. - - - - -## When are Atomic Guards Removed - -Atomic-Guards expire on the expiration of the documents they are used for and are automatically -removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. - - -Since different cleanup tasks handle the removal of deleted and expired documents -and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed -documents would linger in the compare exchange entries list a short while longer before -they are removed. - -* You do **not** need to remove such Atomic-Guards yourself, they will be removed by - the cleanup task. -* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. - RavenDB will create new Atomic-Guards for such documents, and expire the old ones. - - - - - diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/atomic-guards.mdx index 2d99597a49..97044028b9 100644 --- a/versioned_docs/version-5.2/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-5.2/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/compare-exchange.mdx index 3693f7b9bf..d2305f1c22 100644 --- a/versioned_docs/version-5.2/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-5.2/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..810f6510f3 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,191 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) + key/value items that RavenDB creates and manages automatically to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) + transactions in cluster-wide sessions. + Each document will be associated with its own unique Atomic-Guard item. + +* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. + Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, + which is triggered by changing the document. + +* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to + administer compare-exchange entries explicitly. You can still do that if you wish by + [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + the automatic usage of atomic-guards in a session and defining and managing compare exchange + key/value pairs + [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) + where needed. + * **We strongly recommend not managing atomic-guards manually** unless you _truly_ know what you're doing. + Doing so could cancel RavenDB's ACID transaction guarantees. + +* In this page: + * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) + * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) + * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) + * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + + +## How Atomic Guards Work + +Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. +The Atomic-Guards are managed as follows: + +* __New document__: + A new Atomic-Guard is created when successfully saving a new document. + +* __Existing document that doesn't have an Atomic-Guard__: + A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. + +* __Existing document that already has an Atomic-Guard__: + + * Whenever one session modifies a document that already has an associated Atomic-Guard, + the value of its related Atomic-Guard increases. + This allows RavenDB to detect that changes were made to this document. + + * If other sessions have loaded the document before the version changed, + they will not be able to modify it if trying to save after the first session already saved it, + and a `ConcurrencyException` will be thrown. + + * If the session `SaveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. + Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. + + + +## Atomic Guard Transaction Scope + +* Atomic-Guards are local to the database they were defined on. + +* Since Atomic-Guards are implemented as compare-exchange items, + they are Not externally replicated to another database by any ongoing replication task. + Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Syntax and Usage + +In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, +and then used when two sessions compete on changing the document. + + + +{`using (var session = store.OpenAsyncSession(new SessionOptions + \{ + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + \})) +\{ + await session.StoreAsync(new User(), "users/johndoe"); + await session.SaveChangesAsync(); + // An atomic-guard is now automatically created for the new document "users/johndoe". +\} + +// Open two more cluster-wide sessions +using (var session1 = store.OpenAsyncSession( + new SessionOptions + \{TransactionMode = TransactionMode.ClusterWide\})) +using (var session2 = store.OpenAsyncSession( + new SessionOptions + \{TransactionMode = TransactionMode.ClusterWide\})) +\{ + // The two sessions will load the same document at the same time + var loadedUser1 = await session1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await session2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // Session1 will save changes first, which triggers a change in the + // version number of the associated atomic-guard. + await session1.SaveChangesAsync(); + + // session2.saveChanges() will be rejected with ConcurrencyException + // since session1 already changed the atomic-guard version, + // and session2 saveChanges uses the document version that it had when it loaded the document. + await session2.SaveChangesAsync(); +\} +`} + + + +After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, +in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +The generated Atomic-Guard key name is composed of: + + * The prefix `rvn-atomic` + * The ID of the document that it is associated with + + + +## Disabling Atomic Guards + +To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session +`DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + +In the sample below, the session uses **no Atomic-Guards**. + + +{`using (var session = store.OpenAsyncSession(new SessionOptions + \{ + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + \})) +\{ + await session.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await session.SaveChangesAsync(); +\} +`} + + + + + +* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, + you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) + the required compare exchange key/value pairs. + +* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively + impact ACID transaction guarantees. + +* **Do not remove or edit** Atomic-Guards manually while a session is using them. + A session that is currently using these removed Atomic-Guards will not be able to save + their related documents resulting in an error. + * If you accidentally remove an active Atomic-Guard that is associated with an existing document, + recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. + + + + +## When are Atomic Guards Removed + +Atomic guards expire on the expiration of the documents they are used for and are automatically +removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. + + +Since different cleanup tasks handle the removal of deleted and expired documents +and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed +documents would linger in the compare exchange entries list a short while longer before +they are removed. + +* You do **not** need to remove such Atomic-Guards yourself, they will be removed by + the cleanup task. +* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. + RavenDB will create new Atomic-Guards for such documents, and expire the old ones. + + + + + diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..936efaac78 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,192 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) + key/value items that RavenDB creates and manages automatically to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) + transactions in cluster-wide sessions. + Each document will be associated with its own unique Atomic-Guard item. + +* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. + Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, + which is triggered by changing the document. + +* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to + administer compare-exchange entries explicitly. You can still do that if you wish by + [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + the automatic usage of Atomic-Guards in a session and defining and managing compare exchange + key/value pairs + [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) + where needed. + * **We strongly recommend not managing Atomic-Guards manually** unless you _truly_ know what you're doing. + Doing so could cancel RavenDB's ACID transaction guarantees. + +* In this page: + * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) + * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) + * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) + * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + + +## How Atomic Guards Work + +Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. +The Atomic-Guards are managed as follows: + +* __New document__: + A new Atomic-Guard is created when successfully saving a new document. + +* __Existing document that doesn't have an Atomic-Guard__: + A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. + +* __Existing document that already has an Atomic-Guard__: + + * Whenever one session modifies a document that already has an associated Atomic-Guard, + the value of its related Atomic-Guard increases. + This allows RavenDB to detect that changes were made to this document. + + * If other sessions have loaded the document before the version changed, + they will not be able to modify it if trying to save after the first session already saved it, + and a `ConcurrencyException` will be thrown. + + * If the session `saveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. + Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. + + + +## Atomic Guard Transaction Scope + +* Atomic-Guards are local to the database they were defined on. + +* Since Atomic-Guards are implemented as compare-exchange items, + they are Not externally replicated to another database by any ongoing replication task. + Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Syntax and Usage + +In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, +and then used when two sessions compete on changing the document. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two more cluster-wide sessions +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// The two sessions will load the same document at the same time +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 will save changes first, which triggers a change in the +// version number of the associated atomic-guard. +await session1.saveChanges(); + +// session2.saveChanges() will be rejected with a ClusterTransactionConcurrencyException +// since session1 already changed the atomic-guard version, +// and session2 saveChanges uses the document version that it had when it loaded the document. +await session2.saveChanges(); +`} + + + +After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, +in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +The generated Atomic-Guard key name is composed of: + +* The prefix `rvn-atomic` +* The ID of the document that it is associated with + + + +## Disabling Atomic Guards + +To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session +`disableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + +In the sample below, the session uses **no Atomic-Guards**. + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, + you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) + the required compare exchange key/value pairs. + +* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively + impact ACID transaction guarantees. + +* **Do not remove or edit** Atomic-Guards manually while a session is using them. + A session that is currently using these removed Atomic-Guards will not be able to save + their related documents resulting in an error. + * If you accidentally remove an active Atomic-Guard that is associated with an existing document, + recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. + + + + +## When are Atomic Guards Removed + +Atomic-Guards expire on the expiration of the documents they are used for and are automatically +removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. + + +Since different cleanup tasks handle the removal of deleted and expired documents +and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed +documents would linger in the compare exchange entries list a short while longer before +they are removed. + +* You do **not** need to remove such Atomic-Guards yourself, they will be removed by + the cleanup task. +* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. + RavenDB will create new Atomic-Guards for such documents, and expire the old ones. + + + + + diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-5.2/client-api/session/cluster-transaction/overview.mdx index 6787bd6be7..a26704cabc 100644 --- a/versioned_docs/version-5.2/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-5.2/client-api/session/cluster-transaction/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-tracking.mdx index 1399fe8c0b..49c6ebd8a1 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-5.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-5.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-5.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/deleting-entities.mdx b/versioned_docs/version-5.2/client-api/session/deleting-entities.mdx index 0e46a545bd..2f3f6db846 100644 --- a/versioned_docs/version-5.2/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-5.2/client-api/session/how-to/check-if-attachment-exists.mdx index 379619b069..62f1018333 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-5.2/client-api/session/how-to/check-if-document-exists.mdx index f41ee097a2..2e11ba9929 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/check-if-document-exists.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-5.2/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-5.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-5.2/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-5.2/client-api/session/how-to/defer-operations.mdx index 5854e379c5..309a2e5034 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/defer-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-5.2/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-counters.mdx index 18359541bb..7a76778c86 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-5.2/client-api/session/how-to/ignore-entity-changes.mdx index c9c6522156..e01e528248 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-5.2/client-api/session/how-to/perform-operations-lazily.mdx index 7d627b5024..fa70ee89c9 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-5.2/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-5.2/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-5.2/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-5.2/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/loading-entities.mdx b/versioned_docs/version-5.2/client-api/session/loading-entities.mdx index 7f2d580494..f473ea6116 100644 --- a/versioned_docs/version-5.2/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/opening-a-session.mdx b/versioned_docs/version-5.2/client-api/session/opening-a-session.mdx index 8354581dea..3cb63fa64a 100644 --- a/versioned_docs/version-5.2/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-5.2/client-api/session/opening-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 77ba83eeda..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,215 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) - ----- - - -## Query the collection (dynamic query) - -* You can make a dynamic query on a collection to find which documents are missing the specified field. - -* Use extension methods `Not` & `WhereExists` that are accessible from [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx). - -* This will either create a new auto-index or add the queried field to an existing auto-index. - Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - - - -__Example__ - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query a static index - -* You can search for documents with missing fields by querying a static index. - -* The index definition must have the following document-fields indexed: - - 1. The field that is suspected to be __missing in some documents__. - - 2. A document-field that __exists in all documents__ in the collection, - (i.e. the _Id_ field, or any other field that is common to all). - Indexing such a field is mandatory so that all documents in the collection will be indexed. - - - -__Example__ - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query by RQL in Studio - -* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause, - first search for a field that __exists__ in every document in the collection, - and then search for the field that __may not exist__ in some of document. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the RQL query. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (Field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index c91513c241..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,170 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) - ----- - - -## Query the collection (dynamic query) - -* You can make a dynamic query on a collection to find which documents are missing the specified field. - -* Use extension methods `not` & `whereExists` that are accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API. - -* This will either create a new auto-index or add the queried field to an existing auto-index. - Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - - - -__Example__ - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query a static index - -* You can search for documents with missing fields by querying a static index. - -* The index definition must have the following document-fields indexed: - - 1. The field that is suspected to be __missing in some documents__. - - 2. A document-field that __exists in all documents__ in the collection, - (i.e. the _id_ field, or any other field that is common to all). - Indexing such a field is mandatory so that all documents in the collection will be indexed. - - - -__Example__ - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query by RQL in Studio - -* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - - -{`from "orders" -where exists("company") and not exists("freight") -`} - - - -* In the `where` clause, - first search for a field that __exists__ in every document in the collection, - and then search for the field that __may not exist__ in some of document. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the RQL query. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (Field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index ec6956b550..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,991 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You have two options: - - * __Dynamic spatial query__ - Either make a dynamic spatial query on a collection ( __described in this article__ ). - An auto-index will be created by the server. - - * __Spatial index query__ - Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from the Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### Spatial - - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __path__ | `Expression>` | Path to spatial field in an index
(when querying an index) | -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index) | -| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| __clause__ | `Func` | Spatial criteria that will be executed on a given spatial field | - -#### DynamicSpatialFieldFactory - - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| __latitudePath__ / __longitudePath__ / __wktPath__ | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -#### SpatialCriteriaFactory - - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `double` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### OrderByDistance - - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -#### OrderByDistanceDescending - - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __path__ | `Expression>` | Path to spatial field in index
(when querying an index) | -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index) | -| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `double` | Used to define a point from which distance will be measured | -| __roundFactor__ | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index 11723f7cb7..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,504 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You have two options: - - * __Dynamic spatial query__ - Either make a dynamic spatial query on a collection ( __described in this article__ ). - An auto-index will be created by the server. - - * __Spatial index query__ - Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from the Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 0cf3ae0b47..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer __similar terms__ from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a __dynamic-query__. - For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into __terms__ that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * __When query has no results__: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * __When looking for alternative terms__: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. __The field name__ - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -__Suggest using__: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| __suggestion__ | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| __builder__ | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -__Builder operations__: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| __fieldName__ | `string` | The index field in which to search for similar terms | -| __path__ | `Expression>` | The index field in which to search for similar terms | -| __term__ | `string` | The term for which to get suggested similar terms | -| __terms__ | `string[]` | List of terms for which to get suggested similar terms | -| __displayName__ | `string` | A custom name for the suggestions result (optional). | -| __options__ | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -__Suggestions options__: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 4ea7647395..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer __similar terms__ from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a __dynamic-query__. - For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into __terms__ that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * __When query has no results__: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * __When looking for alternative terms__: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the __Northwind sample data__, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. __The field name__ - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -__Suggest using__: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| __action__ | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -__Builder operations__: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | The index field in which to search for similar terms | -| __term__ | `string` | The term for which to get suggested similar terms | -| __terms__ | `string[]` | List of terms for which to get suggested similar terms | -| __displayName__ | `string` | A custom name for the suggestions result (optional). | -| __options__ | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -__Suggestions options__: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..f1f89ef8ef --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,215 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) + +---- + + +## Query the collection (dynamic query) + +* You can make a dynamic query on a collection to find which documents are missing the specified field. + +* Use extension methods `Not` & `WhereExists` that are accessible from [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx). + +* This will either create a new auto-index or add the queried field to an existing auto-index. + Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + + + +__Example__ + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query a static index + +* You can search for documents with missing fields by querying a static index. + +* The index definition must have the following document-fields indexed: + + 1. The field that is suspected to be __missing in some documents__. + + 2. A document-field that __exists in all documents__ in the collection, + (i.e. the _Id_ field, or any other field that is common to all). + Indexing such a field is mandatory so that all documents in the collection will be indexed. + + + +__Example__ + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query by RQL in Studio + +* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause, + first search for a field that __exists__ in every document in the collection, + and then search for the field that __may not exist__ in some of document. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the RQL query. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (Field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..91158357a8 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,170 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) + +---- + + +## Query the collection (dynamic query) + +* You can make a dynamic query on a collection to find which documents are missing the specified field. + +* Use extension methods `not` & `whereExists` that are accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API. + +* This will either create a new auto-index or add the queried field to an existing auto-index. + Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + + + +__Example__ + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query a static index + +* You can search for documents with missing fields by querying a static index. + +* The index definition must have the following document-fields indexed: + + 1. The field that is suspected to be __missing in some documents__. + + 2. A document-field that __exists in all documents__ in the collection, + (i.e. the _id_ field, or any other field that is common to all). + Indexing such a field is mandatory so that all documents in the collection will be indexed. + + + +__Example__ + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query by RQL in Studio + +* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + + +{`from "orders" +where exists("company") and not exists("freight") +`} + + + +* In the `where` clause, + first search for a field that __exists__ in every document in the collection, + and then search for the field that __may not exist__ in some of document. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the RQL query. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (Field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..791e505612 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,991 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You have two options: + + * __Dynamic spatial query__ + Either make a dynamic spatial query on a collection ( __described in this article__ ). + An auto-index will be created by the server. + + * __Spatial index query__ + Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from the Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### Spatial + + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __path__ | `Expression>` | Path to spatial field in an index
(when querying an index) | +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index) | +| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| __clause__ | `Func` | Spatial criteria that will be executed on a given spatial field | + +#### DynamicSpatialFieldFactory + + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| __latitudePath__ / __longitudePath__ / __wktPath__ | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +#### SpatialCriteriaFactory + + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `double` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### OrderByDistance + + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +#### OrderByDistanceDescending + + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __path__ | `Expression>` | Path to spatial field in index
(when querying an index) | +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index) | +| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `double` | Used to define a point from which distance will be measured | +| __roundFactor__ | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..57d21633b0 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,504 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You have two options: + + * __Dynamic spatial query__ + Either make a dynamic spatial query on a collection ( __described in this article__ ). + An auto-index will be created by the server. + + * __Spatial index query__ + Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from the Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..527562a055 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer __similar terms__ from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a __dynamic-query__. + For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into __terms__ that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * __When query has no results__: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * __When looking for alternative terms__: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. __The field name__ - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +__Suggest using__: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| __suggestion__ | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| __builder__ | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +__Builder operations__: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| __fieldName__ | `string` | The index field in which to search for similar terms | +| __path__ | `Expression>` | The index field in which to search for similar terms | +| __term__ | `string` | The term for which to get suggested similar terms | +| __terms__ | `string[]` | List of terms for which to get suggested similar terms | +| __displayName__ | `string` | A custom name for the suggestions result (optional). | +| __options__ | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +__Suggestions options__: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..cd1c1eb260 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer __similar terms__ from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a __dynamic-query__. + For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into __terms__ that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * __When query has no results__: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * __When looking for alternative terms__: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the __Northwind sample data__, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. __The field name__ - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +__Suggest using__: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| __action__ | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +__Builder operations__: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | The index field in which to search for similar terms | +| __term__ | `string` | The term for which to get suggested similar terms | +| __terms__ | `string[]` | List of terms for which to get suggested similar terms | +| __displayName__ | `string` | A custom name for the suggestions result (optional). | +| __options__ | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +__Suggestions options__: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index 8de03a799b..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,104 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a __score__. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* __To get the score details__ and see how it was calculated, - you can use `IncludeExplanations` when querying with a [DocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Query with \`DocumentQuery\` -var results = session.Advanced.DocumentQuery() - - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(results[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var results = await asyncSession.Advanced.AsyncDocumentQuery() - - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(results[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the __Query view__ in the Studio. - -* Running a query with `include explanations()` will show an additional __Explanations Tab__. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 9e5b23ad54..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,95 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a __score__. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query __to get the score details__ and see how it was calculated. - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const results = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explenations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const scoreDetails = explanationsResults.explanations[productResults[0].id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the __Query view__ in the Studio. -* Running a query with `include explanations()` will show an additional __Explanations Tab__. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - -<small> __The Explanations object__: </small> - - -{`class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index ad145fbf55..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index b4c6b9da8a..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 389cd336ce..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,97 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..d142e7c758 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,104 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a __score__. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* __To get the score details__ and see how it was calculated, + you can use `IncludeExplanations` when querying with a [DocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Query with \`DocumentQuery\` +var results = session.Advanced.DocumentQuery() + + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(results[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var results = await asyncSession.Advanced.AsyncDocumentQuery() + + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(results[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the __Query view__ in the Studio. + +* Running a query with `include explanations()` will show an additional __Explanations Tab__. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..f594fc887e --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,95 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a __score__. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query __to get the score details__ and see how it was calculated. + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const results = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explenations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const scoreDetails = explanationsResults.explanations[productResults[0].id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the __Query view__ in the Studio. +* Running a query with `include explanations()` will show an additional __Explanations Tab__. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + +<small> __The Explanations object__: </small> + + +{`class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..416987fcd3 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..2181b57837 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..a92e9ce1f3 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,97 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/include-explanations.mdx index 521eae33e2..a398b3efa5 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/include-explanations.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-5.2/client-api/session/querying/debugging/query-timings.mdx index 7663264dbb..f95a1b302c 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/debugging/query-timings.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/query-vs-document-query.mdx index b5136f5c1e..db01c023aa 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/document-query/what-is-document-query.mdx index d7a4d4ff71..ac20723481 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-count-query-results.mdx index 5318fd5abb..004f7ead31 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-count-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-customize-query.mdx index aad41a1873..ae69eb4255 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-field.mdx index 22bcfb442c..0bfcf6f7b4 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index e99c7c48ec..30a68f9ad5 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-get-query-statistics.mdx index 898ccdc414..6fed1cfc62 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-make-a-spatial-query.mdx index d38261b5fe..fe60279a62 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx index aedcc244ca..e4b8a706e0 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-queries-lazily.mdx index 12efb93d4d..7a56389fb9 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-project-query-results.mdx index aef01d210b..b469e21d78 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-query.mdx index 9c593fb421..87039948b8 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-5.2/client-api/session/querying/how-to-work-with-suggestions.mdx index f21a0074f3..bd02108b2e 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/sort-query-results.mdx index e69d03116c..a6ca4d0210 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/sort-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index 90790d2ef7..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __path__ | `Expression>` | Path to the field that contains the searched terms to highlight. | -| __fragmentLength__ | int | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | int | Maximum number of text fragments that will be returned. | -| __options__ | `HighlightingOptions` | Customizing options. | -| __highlightings__ | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -__Highlighting options__: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __GroupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __PreTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __PostTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__Highlightings object__: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| __FieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __ResultIndents__ | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| __GetFragments__ | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/boost-search-results.mdx index 05616535dd..459d7e1e2b 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..4f74546abc --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __path__ | `Expression>` | Path to the field that contains the searched terms to highlight. | +| __fragmentLength__ | int | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | int | Maximum number of text fragments that will be returned. | +| __options__ | `HighlightingOptions` | Customizing options. | +| __highlightings__ | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +__Highlighting options__: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __GroupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __PreTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __PostTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__Highlightings object__: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| __FieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __ResultIndents__ | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| __GetFragments__ | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/ends-with-query.mdx index c2535d37a8..0bb4e0e597 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/exact-match-query.mdx index 0548f020e2..ec244ac053 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/full-text-search.mdx index 78ac594a53..f54a6e4e62 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/full-text-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/fuzzy-search.mdx index 9e195d4290..e146956ec5 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/highlight-query-results.mdx index d890b4d123..2003d34238 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/proximity-search.mdx index 12a1a3ce5d..091ea6ad65 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/proximity-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/starts-with-query.mdx index f5f965cf18..f139ef9545 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-5.2/client-api/session/querying/text-search/using-regex.mdx index a9dae3e72c..afc9483db5 100644 --- a/versioned_docs/version-5.2/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-5.2/client-api/session/querying/text-search/using-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_counter-revisions-csharp.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_counter-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_counter-revisions-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_counter-revisions-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_counter-revisions-java.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_counter-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_counter-revisions-java.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_counter-revisions-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_loading-csharp.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_loading-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_loading-java.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_loading-java.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_loading-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_loading-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_loading-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-csharp.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-csharp.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-java.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-java.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-java.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-nodejs.mdx b/versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/session/revisions/_what-are-revisions-nodejs.mdx rename to versioned_docs/version-5.2/client-api/session/revisions/content/_what-are-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/session/revisions/counter-revisions.mdx b/versioned_docs/version-5.2/client-api/session/revisions/counter-revisions.mdx index 2685ffaefe..096cb444a7 100644 --- a/versioned_docs/version-5.2/client-api/session/revisions/counter-revisions.mdx +++ b/versioned_docs/version-5.2/client-api/session/revisions/counter-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterRevisionsCsharp from './_counter-revisions-csharp.mdx'; -import CounterRevisionsJava from './_counter-revisions-java.mdx'; +import CounterRevisionsCsharp from './content/_counter-revisions-csharp.mdx'; +import CounterRevisionsJava from './content/_counter-revisions-java.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/revisions/loading.mdx b/versioned_docs/version-5.2/client-api/session/revisions/loading.mdx index 742c5b083a..1277489d9f 100644 --- a/versioned_docs/version-5.2/client-api/session/revisions/loading.mdx +++ b/versioned_docs/version-5.2/client-api/session/revisions/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/revisions/what-are-revisions.mdx b/versioned_docs/version-5.2/client-api/session/revisions/what-are-revisions.mdx index b436059795..531505109a 100644 --- a/versioned_docs/version-5.2/client-api/session/revisions/what-are-revisions.mdx +++ b/versioned_docs/version-5.2/client-api/session/revisions/what-are-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreRevisionsCsharp from './_what-are-revisions-csharp.mdx'; -import WhatAreRevisionsJava from './_what-are-revisions-java.mdx'; -import WhatAreRevisionsNodejs from './_what-are-revisions-nodejs.mdx'; +import WhatAreRevisionsCsharp from './content/_what-are-revisions-csharp.mdx'; +import WhatAreRevisionsJava from './content/_what-are-revisions-java.mdx'; +import WhatAreRevisionsNodejs from './content/_what-are-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/saving-changes.mdx b/versioned_docs/version-5.2/client-api/session/saving-changes.mdx index 31d3090030..c6d8b6b7b2 100644 --- a/versioned_docs/version-5.2/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-5.2/client-api/session/saving-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/storing-entities.mdx b/versioned_docs/version-5.2/client-api/session/storing-entities.mdx index c8409107c9..fb5d92b576 100644 --- a/versioned_docs/version-5.2/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/updating-entities.mdx b/versioned_docs/version-5.2/client-api/session/updating-entities.mdx index d32cd550a0..51396db0de 100644 --- a/versioned_docs/version-5.2/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-5.2/client-api/session/updating-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-5.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx index e27431ce62..e4170c24e5 100644 --- a/versioned_docs/version-5.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-5.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-5.2/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-5.2/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-5.2/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/setting-up-default-database.mdx b/versioned_docs/version-5.2/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-5.2/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-5.2/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-5.2/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-5.2/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-5.2/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-5.2/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-5.2/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/client-api/what-is-a-document-store.mdx b/versioned_docs/version-5.2/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-5.2/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-5.2/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-5.2/document-extensions/attachments/copying-moving-renaming.mdx index b9774d0444..65484c9d78 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/deleting.mdx b/versioned_docs/version-5.2/document-extensions/attachments/deleting.mdx index 6259980cd3..3a916d6185 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/indexing.mdx b/versioned_docs/version-5.2/document-extensions/attachments/indexing.mdx index 952c7c850c..effc2fb8a1 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/loading.mdx b/versioned_docs/version-5.2/document-extensions/attachments/loading.mdx index 9df0597641..13d7ce3ad5 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/storing.mdx b/versioned_docs/version-5.2/document-extensions/attachments/storing.mdx index 63f3d6f602..f9646cbe1f 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-5.2/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-5.2/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-5.2/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-5.2/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-5.2/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-5.2/document-extensions/counters/counters-and-other-features.mdx index d567f37006..217b2590a4 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/counters-and-other-features.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-5.2/document-extensions/counters/create-or-modify.mdx index 5e8c29ec4a..8f8d71dfef 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/delete.mdx b/versioned_docs/version-5.2/document-extensions/counters/delete.mdx index 949fb2feed..d1e2ffe8a1 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/indexing.mdx b/versioned_docs/version-5.2/document-extensions/counters/indexing.mdx index 3631c6ba3a..fc79f90af0 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/overview.mdx b/versioned_docs/version-5.2/document-extensions/counters/overview.mdx index bf20ec9bcd..50c52e0ffe 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-5.2/document-extensions/counters/retrieve-counter-values.mdx index acd7025f97..669bcfbff9 100644 --- a/versioned_docs/version-5.2/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-5.2/document-extensions/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-5.2/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-5.2/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-5.2/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-5.2/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-5.2/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-5.2/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-5.2/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-5.2/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-5.2/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-5.2/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-5.2/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_index-query-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_index-query-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_query-result-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_query-result-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/_stream-result-csharp.mdx b/versioned_docs/version-5.2/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-5.2/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-5.2/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-5.2/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-5.2/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/counters-batch-command-data.mdx b/versioned_docs/version-5.2/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-5.2/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/delete-command-data.mdx b/versioned_docs/version-5.2/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-5.2/glossary/delete-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-5.2/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-5.2/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/index-query.mdx b/versioned_docs/version-5.2/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-5.2/glossary/index-query.mdx +++ b/versioned_docs/version-5.2/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/move-attachment-command-data.mdx b/versioned_docs/version-5.2/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-5.2/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/patch-command-data.mdx b/versioned_docs/version-5.2/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-5.2/glossary/patch-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/put-command-data.mdx b/versioned_docs/version-5.2/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-5.2/glossary/put-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-5.2/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-5.2/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.2/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/query-result.mdx b/versioned_docs/version-5.2/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-5.2/glossary/query-result.mdx +++ b/versioned_docs/version-5.2/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/stream-query-statistics.mdx b/versioned_docs/version-5.2/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-5.2/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-5.2/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-5.2/glossary/stream-result.mdx b/versioned_docs/version-5.2/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-5.2/glossary/stream-result.mdx +++ b/versioned_docs/version-5.2/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index a65d3ec381..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,206 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Use the indexing `Recurse` method to recurse through the layers of a hierarchical document -and index its elements. - -* In this Page: - * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) - - -## Hierarchical Data - -One of the significant advantages offered by document databases is their tendency not to force -limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: -take, for example, the commonly-used **Comment thread**, implemented using objects such as: - - -{`private class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Comments can be left recursively - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments -to its Comments field. And readers of these comments can reply with comments of their own, creating -a recursive hierarchical structure. - -`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of -comments left by various authors. - -`BlogPosts/1-A`: - - -{`\{ - "Author ": "John", - "Comments": [ - \{ - "Author": "Moon", - "Comments": [ - \{ - "Author": "Bob" - \}, - \{ - "Author": "Adel", - "Comments": \{ - "Author": "Moon" - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Indexing Hierarchical Data - -To index the elements of a hierarchical structure like the one demonstrated above, -use RavenDB's `Recurse` method. - -In the sample below, we use `Recurse` to go through comments in the post thread -and index them by their authors. - - - -{`private class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class Result - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new Result - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" - } - })); -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - return recurse(blogpost, x => x.Comments).map(function (comment) { - if (comment.Author != null) { - return { - Authors: comment.Author - }; - } - }); - });" - }; - } -} -`} - - - -### Querying the created index - -* The index we created can be queried using code. - - - -{`IList results = session - .Query() - .Where(x => x.Authors.Any(a => a == "John")) - .OfType() - .ToList(); -`} - - - - -{`IList results = session - .Advanced - .DocumentQuery() - .WhereEquals("Authors", "John") - .ToList(); -`} - - - - -* The index can also be queried using Studio. - - * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) - view to define and query the index. - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) - indexed by the `Recurse` method. - - !["Query View"](./assets/query-view.png) - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.2/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index be4fe4447a..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,599 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following __Classes__ and __Sample Data__: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - - - __The index__: - - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - __The index-entries__: - -![Simple - index-entries](./assets/indexing-nested-data-1.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - The index has a single index-entry per document (3 entries in this example). - -4. The index-field contains a collection of ALL nested values from the document. - e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: - `{"black", "blue", "red"}` - __Querying the index__: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - __When to use__: - -* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - -* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - -* To address this, you must use a __Fanout index__ - as described below. - - - -## Fanout index - Multiple index-entries per document - - - - __What is a Fanout index__: - -* A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - -* The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - - - - - - __Fanout index - Map index example__: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - __The index-entries__: - -![Fanout - index-entries](./assets/indexing-nested-data-2.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - Each index-entry corresponds to an inner item in the TShirt list. - -4. In this example, the total number of index-entries is __12__, - which is the total number of inner items in the TShirt list in all __3__ documents in the collection. - - - - - - __Fanout index - Map-Reduce index example__: - -* The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - - - - - - __Fanout index - Performance hints__: - -* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - -* When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. - -* You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - -* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -* Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - - - - - - __Fanout index - Paging__: - -* A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - -* When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - -* __To overcome this when paging results__, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - -* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-5.2/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.2/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index 608e53adcb..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,420 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following __Classes__ and __Sample Data__: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - - - __The index__: - - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - - __The index-entries__: - -![Simple - index-entries](./assets/indexing-nested-data-1.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - The index has a single index-entry per document (3 entries in this example). - -4. The index-field contains a collection of ALL nested values from the document. - e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: - `{"black", "blue", "red"}` - __Querying the index__: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - __When to use__: - -* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - -* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - -* To address this, you must use a __Fanout index__ - as described below. - - - -## Fanout index - Multiple index-entries per document - - - - __What is a Fanout index__: - -* A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - -* The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - - - - - - __Fanout index - Map index example__: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - __The index-entries__: - -![Fanout - index-entries](./assets/indexing-nested-data-2.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - Each index-entry corresponds to an inner item in the TShirt list. - -4. In this example, the total number of index-entries is __12__, - which is the total number of inner items in the TShirt list in all __3__ documents in the collection. - - - - - - __Fanout index - Map-Reduce index example__: - -* The fanout index concept applies to map-reduce indexes as well: - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - - - - - - __Fanout index - Performance hints__: - -* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - -* When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. - -* You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - -* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -* Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - - - - - - __Fanout index - Paging__: - -* A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - -* When making a fanout index query that should return full documents (without projecting results), - then in this case, the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - -* __To overcome this when paging results__, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - -* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.2/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index a1e6ff4d41..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,468 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, __documents can reference other documents__. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a __Related Document__. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - -![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -__What is tracked__: - -* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -__The documents__: - - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -__The index__: - -* This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -__What is tracked__: - -* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. - Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was __first indexed__ when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the __indexed collection__ will trigger re-indexing. - -* Any such change done on any document in the __indexed related documents__ will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.2/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.2/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 504fe94ea4..0000000000 --- a/versioned_docs/version-5.2/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, __documents can reference other documents__. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a __Related Document__. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - -![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -__What is tracked__: - -* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -__The query__: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -__The documents__: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -__The index__: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -__The query__: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -__What is tracked__: - -* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. - Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -__The query__: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was __first indexed__ when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the __indexed collection__ will trigger re-indexing. - -* Any such change done on any document in the __indexed related documents__ will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.2/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 3e1a4a1693..0000000000 --- a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,574 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'Size' use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents with some 'LastName' use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'ProductType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "Name": "SomeName", - "Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's PropName __value__. - e.g. 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.2/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index f1892d11b3..0000000000 --- a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,500 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -__The query__: - -* To get all documents with some 'lastName' use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName __value__. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.2/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index c568184f2b..0000000000 --- a/versioned_docs/version-5.2/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName __value__. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.2/indexes/boosting.mdx b/versioned_docs/version-5.2/indexes/boosting.mdx index 5db484d2e0..fdae10ce48 100644 --- a/versioned_docs/version-5.2/indexes/boosting.mdx +++ b/versioned_docs/version-5.2/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/_boosting-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_boosting-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_boosting-java.mdx b/versioned_docs/version-5.2/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_boosting-java.mdx rename to versioned_docs/version-5.2/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_boosting-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-5.2/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-5.2/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_extending-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-basics-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..185c74ef37 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,206 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Use the indexing `Recurse` method to recurse through the layers of a hierarchical document +and index its elements. + +* In this Page: + * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) + + +## Hierarchical Data + +One of the significant advantages offered by document databases is their tendency not to force +limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: +take, for example, the commonly-used **Comment thread**, implemented using objects such as: + + +{`private class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Comments can be left recursively + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments +to its Comments field. And readers of these comments can reply with comments of their own, creating +a recursive hierarchical structure. + +`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of +comments left by various authors. + +`BlogPosts/1-A`: + + +{`\{ + "Author ": "John", + "Comments": [ + \{ + "Author": "Moon", + "Comments": [ + \{ + "Author": "Bob" + \}, + \{ + "Author": "Adel", + "Comments": \{ + "Author": "Moon" + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Indexing Hierarchical Data + +To index the elements of a hierarchical structure like the one demonstrated above, +use RavenDB's `Recurse` method. + +In the sample below, we use `Recurse` to go through comments in the post thread +and index them by their authors. + + + +{`private class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class Result + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new Result + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" + } + })); +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + return recurse(blogpost, x => x.Comments).map(function (comment) { + if (comment.Author != null) { + return { + Authors: comment.Author + }; + } + }); + });" + }; + } +} +`} + + + +### Querying the created index + +* The index we created can be queried using code. + + + +{`IList results = session + .Query() + .Where(x => x.Authors.Any(a => a == "John")) + .OfType() + .ToList(); +`} + + + + +{`IList results = session + .Advanced + .DocumentQuery() + .WhereEquals("Authors", "John") + .ToList(); +`} + + + + +* The index can also be queried using Studio. + + * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) + view to define and query the index. + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) + indexed by the `Recurse` method. + + !["Query View"](../assets/query-view.png) + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-hierarchical-data-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-hierarchical-data-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..927d354489 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,599 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following __Classes__ and __Sample Data__: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + + + __The index__: + + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + __The index-entries__: + +![Simple - index-entries](../assets/indexing-nested-data-1.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + The index has a single index-entry per document (3 entries in this example). + +4. The index-field contains a collection of ALL nested values from the document. + e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: + `{"black", "blue", "red"}` + __Querying the index__: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + __When to use__: + +* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + +* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + +* To address this, you must use a __Fanout index__ - as described below. + + + +## Fanout index - Multiple index-entries per document + + + + __What is a Fanout index__: + +* A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + +* The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + + + + + + __Fanout index - Map index example__: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + __The index-entries__: + +![Fanout - index-entries](../assets/indexing-nested-data-2.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + Each index-entry corresponds to an inner item in the TShirt list. + +4. In this example, the total number of index-entries is __12__, + which is the total number of inner items in the TShirt list in all __3__ documents in the collection. + + + + + + __Fanout index - Map-Reduce index example__: + +* The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + + + + + + __Fanout index - Performance hints__: + +* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + +* When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. + +* You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + +* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +* Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + + + + + + __Fanout index - Paging__: + +* A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + +* When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + +* __To overcome this when paging results__, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + +* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + + + diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..cba7f70a7a --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,420 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following __Classes__ and __Sample Data__: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + + + __The index__: + + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + + __The index-entries__: + +![Simple - index-entries](../assets/indexing-nested-data-1.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + The index has a single index-entry per document (3 entries in this example). + +4. The index-field contains a collection of ALL nested values from the document. + e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: + `{"black", "blue", "red"}` + __Querying the index__: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + __When to use__: + +* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + +* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + +* To address this, you must use a __Fanout index__ - as described below. + + + +## Fanout index - Multiple index-entries per document + + + + __What is a Fanout index__: + +* A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + +* The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + + + + + + __Fanout index - Map index example__: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + __The index-entries__: + +![Fanout - index-entries](../assets/indexing-nested-data-2.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + Each index-entry corresponds to an inner item in the TShirt list. + +4. In this example, the total number of index-entries is __12__, + which is the total number of inner items in the TShirt list in all __3__ documents in the collection. + + + + + + __Fanout index - Map-Reduce index example__: + +* The fanout index concept applies to map-reduce indexes as well: + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + + + + + + __Fanout index - Performance hints__: + +* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + +* When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. + +* You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + +* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +* Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + + + + + + __Fanout index - Paging__: + +* A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + +* When making a fanout index query that should return full documents (without projecting results), + then in this case, the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + +* __To overcome this when paging results__, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + +* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + + + diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a768088f06 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,468 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, __documents can reference other documents__. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a __Related Document__. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + +![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +__What is tracked__: + +* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +__The documents__: + + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +__The index__: + +* This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +__What is tracked__: + +* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. + Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was __first indexed__ when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the __indexed collection__ will trigger re-indexing. + +* Any such change done on any document in the __indexed related documents__ will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.2/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..48dd6a0f6d --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, __documents can reference other documents__. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a __Related Document__. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + +![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +__What is tracked__: + +* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +__The query__: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +__The documents__: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +__The index__: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +__The query__: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +__What is tracked__: + +* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. + Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +__The query__: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was __first indexed__ when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the __indexed collection__ will trigger re-indexing. + +* Any such change done on any document in the __indexed related documents__ will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.2/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-5.2/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-5.2/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_stale-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-5.2/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-5.2/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_using-analyzers-java.mdx b/versioned_docs/version-5.2/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-5.2/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..7d94f57de6 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,574 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'Size' use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents with some 'LastName' use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'ProductType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "Name": "SomeName", + "Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's PropName __value__. + e.g. 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..fa1a55a5ab --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,500 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +__The query__: + +* To get all documents with some 'lastName' use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName __value__. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..9c55ce9551 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName __value__. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.2/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-5.2/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-5.2/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.2/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-5.2/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-5.2/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-5.2/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-5.2/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.2/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-5.2/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-5.2/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-5.2/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-5.2/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/creating-and-deploying.mdx b/versioned_docs/version-5.2/indexes/creating-and-deploying.mdx index 1397f3eb69..1f97347e67 100644 --- a/versioned_docs/version-5.2/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-5.2/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/extending-indexes.mdx b/versioned_docs/version-5.2/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-5.2/indexes/extending-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-basics.mdx b/versioned_docs/version-5.2/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-5.2/indexes/indexing-basics.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-5.2/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-5.2/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-5.2/indexes/indexing-hierarchical-data.mdx index 6993053cbe..30fb151b58 100644 --- a/versioned_docs/version-5.2/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-hierarchical-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-5.2/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-5.2/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-nested-data.mdx b/versioned_docs/version-5.2/indexes/indexing-nested-data.mdx index bc3310befc..5752230323 100644 --- a/versioned_docs/version-5.2/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-nested-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-5.2/indexes/indexing-polymorphic-data.mdx index a74cc86adf..6036c211db 100644 --- a/versioned_docs/version-5.2/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-related-documents.mdx b/versioned_docs/version-5.2/indexes/indexing-related-documents.mdx index e28934ff30..343854acdd 100644 --- a/versioned_docs/version-5.2/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-related-documents.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/indexing-spatial-data.mdx b/versioned_docs/version-5.2/indexes/indexing-spatial-data.mdx index 201f538486..9f7cdef92a 100644 --- a/versioned_docs/version-5.2/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-5.2/indexes/indexing-spatial-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/javascript-indexes.mdx b/versioned_docs/version-5.2/indexes/javascript-indexes.mdx index d120b3bc12..70bed49b28 100644 --- a/versioned_docs/version-5.2/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/javascript-indexes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; diff --git a/versioned_docs/version-5.2/indexes/map-indexes.mdx b/versioned_docs/version-5.2/indexes/map-indexes.mdx index ebdf82799c..92d33a920d 100644 --- a/versioned_docs/version-5.2/indexes/map-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/map-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/map-reduce-indexes.mdx b/versioned_docs/version-5.2/indexes/map-reduce-indexes.mdx index 0c1f056942..9ad5b42389 100644 --- a/versioned_docs/version-5.2/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/map-reduce-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/multi-map-indexes.mdx b/versioned_docs/version-5.2/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-5.2/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-5.2/indexes/number-type-conversion.mdx b/versioned_docs/version-5.2/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-5.2/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-5.2/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 83ff4136a7..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1101 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - - - -__Facets definition__: -* Define a list of facets by which to aggregate the data. - -* There are two __Facet types__: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - - - - - - -__Query the index for facets results__: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - - - - - - -__Query results__: -* __Query results__ are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - - - -__Query further__: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - - - -__Facets definition__: -* __Options__ are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - - - - - - -__Query the index for facets results__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - - - -## Facets - Aggregations - - - -__Facets definition__: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - - - - - - -__Query the index for facets results__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - - - -## Storing facets definition in a document - - - - - -__Define and store facets in a document__: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -__Query using facets from document__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| __facets__ | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| __builder__ | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } - public FacetOptions Options { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -__Fluent API builder methods__: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | The index-field to use for the facet | -| __path__ | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| __displayName__ | string | If set, results of a facet will be returned under this name | -| __options__ | `FacetOptions` | Non-default options to use in the facet definition | - -__Options__: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| __TermSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| __Start__ | int | The position from which to send items (how many to skip) | -| __PageSize__ | int | Number of items to return | -| __IncludeRemainingTerms__ | bool | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-5.2/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index df22445cdb..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-5.2/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 74eb0c0698..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,924 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -__Facets definition__: -* Define a list of facets by which to aggregate the data. - -* There are two __Facet types__: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -__Query the index for facets results__: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -__Query results__: -* __Query results__ are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -__Query further__: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -__Facets definition__: -* __Options__ are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -__Query the index for facets results__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -__Facets definition__: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -__Query the index for facets results__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -__Define and store facets in a document__: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -__Query using facets from document__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| __...facet__ | `FacetBase[]` | List containing `FacetBase` implementations. | -| __action__ / __builder__ | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -__builder methods__: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | The index-field to use for the facet | -| __path__ | string | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| __displayName__ | string | If set, results of a facet will be returned under this name | -| __options__ | `FacetOptions` | Non-default options to use in the facet definition | - -__Options__: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| __termSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| __start__ | number | The position from which to send items (how many to skip) | -| __pageSize__ | number | Number of items to return | -| __includeRemainingTerms__ | boolean | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ac51423559..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - - * Optimizes bandwidth usage by reducing data transfer between the server and client. - * Prevents delays in response times caused by sending too much data over the network. - * Avoids high memory consumption when dealing with numerous documents. - * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_paging-java.mdx b/versioned_docs/version-5.2/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 5fa0770eab..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_spatial-java.mdx b/versioned_docs/version-5.2/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index 1dafeb76fa..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,609 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions, and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the __index definition__. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -__Increased indexing time__: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. __The index-field name__ - as defined in the index definition. - In this example the field name is `ProductName`. - -2. __The terms__ that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 2435c4e1f5..0000000000 --- a/versioned_docs/version-5.2/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,342 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions, and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the __index definition__. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -__Increased indexing time__: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the __Northwind sample data__, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. __The index-field name__ - as defined in the index definition. - In this example the field name is `ProductName`. - -2. __The terms__ that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for single term - -Based on the __Northwind sample data__, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.2/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_distinct-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..1ff5577efb --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1101 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + + + +__Facets definition__: +* Define a list of facets by which to aggregate the data. + +* There are two __Facet types__: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + + + + + + +__Query the index for facets results__: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + + + + + + +__Query results__: +* __Query results__ are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + + + +__Query further__: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + + + +__Facets definition__: +* __Options__ are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + + + + + + +__Query the index for facets results__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + + + +## Facets - Aggregations + + + +__Facets definition__: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + + + + + + +__Query the index for facets results__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + + + +## Storing facets definition in a document + + + + + +__Define and store facets in a document__: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +__Query using facets from document__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| __facets__ | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| __builder__ | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } + public FacetOptions Options { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +__Fluent API builder methods__: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | The index-field to use for the facet | +| __path__ | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| __displayName__ | string | If set, results of a facet will be returned under this name | +| __options__ | `FacetOptions` | Non-default options to use in the facet definition | + +__Options__: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| __TermSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| __Start__ | int | The position from which to send items (how many to skip) | +| __PageSize__ | int | Number of items to return | +| __IncludeRemainingTerms__ | bool | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..4ec998bf09 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..7d5cbe3663 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,924 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +__Facets definition__: +* Define a list of facets by which to aggregate the data. + +* There are two __Facet types__: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +__Query the index for facets results__: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +__Query results__: +* __Query results__ are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +__Query further__: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +__Facets definition__: +* __Options__ are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +__Query the index for facets results__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +__Facets definition__: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +__Query the index for facets results__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +__Define and store facets in a document__: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +__Query using facets from document__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| __...facet__ | `FacetBase[]` | List containing `FacetBase` implementations. | +| __action__ / __builder__ | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +__builder methods__: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | The index-field to use for the facet | +| __path__ | string | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| __displayName__ | string | If set, results of a facet will be returned under this name | +| __options__ | `FacetOptions` | Non-default options to use in the facet definition | + +__Options__: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| __termSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| __start__ | number | The position from which to send items (how many to skip) | +| __pageSize__ | number | Number of items to return | +| __includeRemainingTerms__ | boolean | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_filtering-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_intersection-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..2f33d5d05b --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + + * Optimizes bandwidth usage by reducing data transfer between the server and client. + * Prevents delays in response times caused by sending too much data over the network. + * Avoids high memory consumption when dealing with numerous documents. + * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2335739f0 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_projections-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_projections-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_query-index-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_sorting-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.2/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-5.2/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..840a75a167 --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,609 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the __index definition__. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +__Increased indexing time__: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. __The index-field name__ - as defined in the index definition. + In this example the field name is `ProductName`. + +2. __The terms__ that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-5.2/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.2/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-5.2/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-5.2/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-5.2/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..5cc498b16f --- /dev/null +++ b/versioned_docs/version-5.2/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,342 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the __index definition__. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +__Increased indexing time__: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the __Northwind sample data__, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. __The index-field name__ - as defined in the index definition. + In this example the field name is `ProductName`. + +2. __The terms__ that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for single term + +Based on the __Northwind sample data__, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.2/indexes/querying/distinct.mdx b/versioned_docs/version-5.2/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-5.2/indexes/querying/distinct.mdx +++ b/versioned_docs/version-5.2/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/faceted-search.mdx b/versioned_docs/version-5.2/indexes/querying/faceted-search.mdx index d8f05ac087..5bc6531f85 100644 --- a/versioned_docs/version-5.2/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-5.2/indexes/querying/faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/filtering.mdx b/versioned_docs/version-5.2/indexes/querying/filtering.mdx index 8f6d6600e6..22a9e5f917 100644 --- a/versioned_docs/version-5.2/indexes/querying/filtering.mdx +++ b/versioned_docs/version-5.2/indexes/querying/filtering.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/highlighting.mdx b/versioned_docs/version-5.2/indexes/querying/highlighting.mdx index 98ed24c787..30404650cd 100644 --- a/versioned_docs/version-5.2/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-5.2/indexes/querying/highlighting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/intersection.mdx b/versioned_docs/version-5.2/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-5.2/indexes/querying/intersection.mdx +++ b/versioned_docs/version-5.2/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/morelikethis.mdx b/versioned_docs/version-5.2/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-5.2/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-5.2/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/paging.mdx b/versioned_docs/version-5.2/indexes/querying/paging.mdx index 0f8b5f2119..afb88f4e87 100644 --- a/versioned_docs/version-5.2/indexes/querying/paging.mdx +++ b/versioned_docs/version-5.2/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/projections.mdx b/versioned_docs/version-5.2/indexes/querying/projections.mdx index 19060c8668..55e7ce64bf 100644 --- a/versioned_docs/version-5.2/indexes/querying/projections.mdx +++ b/versioned_docs/version-5.2/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/query-index.mdx b/versioned_docs/version-5.2/indexes/querying/query-index.mdx index 265cf6ac4d..be7aad31ee 100644 --- a/versioned_docs/version-5.2/indexes/querying/query-index.mdx +++ b/versioned_docs/version-5.2/indexes/querying/query-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/searching.mdx b/versioned_docs/version-5.2/indexes/querying/searching.mdx index aa9612803b..f2c874aa54 100644 --- a/versioned_docs/version-5.2/indexes/querying/searching.mdx +++ b/versioned_docs/version-5.2/indexes/querying/searching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/sorting.mdx b/versioned_docs/version-5.2/indexes/querying/sorting.mdx index 813b9b7d90..7e2a212636 100644 --- a/versioned_docs/version-5.2/indexes/querying/sorting.mdx +++ b/versioned_docs/version-5.2/indexes/querying/sorting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/spatial.mdx b/versioned_docs/version-5.2/indexes/querying/spatial.mdx index faa4bafa44..f21e0d149d 100644 --- a/versioned_docs/version-5.2/indexes/querying/spatial.mdx +++ b/versioned_docs/version-5.2/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-5.2/indexes/querying/suggestions.mdx b/versioned_docs/version-5.2/indexes/querying/suggestions.mdx index 21373a5ec6..683ca785cd 100644 --- a/versioned_docs/version-5.2/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-5.2/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/sorting-and-collation.mdx b/versioned_docs/version-5.2/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-5.2/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-5.2/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-5.2/indexes/stale-indexes.mdx b/versioned_docs/version-5.2/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-5.2/indexes/stale-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/storing-data-in-index.mdx b/versioned_docs/version-5.2/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-5.2/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-5.2/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/using-analyzers.mdx b/versioned_docs/version-5.2/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-5.2/indexes/using-analyzers.mdx +++ b/versioned_docs/version-5.2/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/using-dynamic-fields.mdx b/versioned_docs/version-5.2/indexes/using-dynamic-fields.mdx index ee3eaf7804..570965a08c 100644 --- a/versioned_docs/version-5.2/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-5.2/indexes/using-dynamic-fields.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/using-term-vectors.mdx b/versioned_docs/version-5.2/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-5.2/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-5.2/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/indexes/what-are-indexes.mdx b/versioned_docs/version-5.2/indexes/what-are-indexes.mdx index 57c6232bef..a50a4aad00 100644 --- a/versioned_docs/version-5.2/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-5.2/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/server/_embedded-csharp.mdx b/versioned_docs/version-5.2/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/server/_embedded-csharp.mdx rename to versioned_docs/version-5.2/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-5.2/server/_embedded-java.mdx b/versioned_docs/version-5.2/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-5.2/server/_embedded-java.mdx rename to versioned_docs/version-5.2/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-5.2/server/embedded.mdx b/versioned_docs/version-5.2/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-5.2/server/embedded.mdx +++ b/versioned_docs/version-5.2/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-5.2/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-5.2/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-5.2/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-5.2/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-5.2/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.2/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-5.2/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-5.2/server/storage/documents-compression.mdx b/versioned_docs/version-5.2/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-5.2/server/storage/documents-compression.mdx +++ b/versioned_docs/version-5.2/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-5.2/start/_test-driver-csharp.mdx b/versioned_docs/version-5.2/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.2/start/_test-driver-csharp.mdx rename to versioned_docs/version-5.2/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-5.2/start/_test-driver-java.mdx b/versioned_docs/version-5.2/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-5.2/start/_test-driver-java.mdx rename to versioned_docs/version-5.2/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-5.2/start/test-driver.mdx b/versioned_docs/version-5.2/start/test-driver.mdx index caaf54ab4c..76d2299c77 100644 --- a/versioned_docs/version-5.2/start/test-driver.mdx +++ b/versioned_docs/version-5.2/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-5.3/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-5.3/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-5.3/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-5.3/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-5.3/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-5.3/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-5.3/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-5.3/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-5.3/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-5.3/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-5.3/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-5.3/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-5.3/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-5.3/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-5.3/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-5.3/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-5.3/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-5.3/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-5.3/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-5.3/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-5.3/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-5.3/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-5.3/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-5.3/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-5.3/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 3fbea43e2e..eaccf2717d 100644 --- a/versioned_docs/version-5.3/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-5.3/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-5.3/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/delete.mdx b/versioned_docs/version-5.3/client-api/commands/documents/delete.mdx index 17a54e69f8..2015818b68 100644 --- a/versioned_docs/version-5.3/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-5.3/client-api/commands/documents/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/commands/documents/get.mdx b/versioned_docs/version-5.3/client-api/commands/documents/get.mdx index 10f9ee95ec..399a753b59 100644 --- a/versioned_docs/version-5.3/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-5.3/client-api/commands/documents/get.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-5.3/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-5.3/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-5.3/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-5.3/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-5.3/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-5.3/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-5.3/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/commands/documents/put.mdx b/versioned_docs/version-5.3/client-api/commands/documents/put.mdx index 1178a97257..016c1f2cb7 100644 --- a/versioned_docs/version-5.3/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-5.3/client-api/commands/documents/put.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_querying-java.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-5.3/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-5.3/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/conventions.mdx b/versioned_docs/version-5.3/client-api/configuration/conventions.mdx index dfa17b75ef..c53640c457 100644 --- a/versioned_docs/version-5.3/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/conventions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/deserialization.mdx b/versioned_docs/version-5.3/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-5.3/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-5.3/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-5.3/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.3/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-5.3/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.3/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/load-balance-behavior.mdx index c362cda8f6..da0fb2a1ac 100644 --- a/versioned_docs/version-5.3/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-5.3/client-api/configuration/load-balance/read-balance-behavior.mdx index 269c259de1..5605fa9f14 100644 --- a/versioned_docs/version-5.3/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/querying.mdx b/versioned_docs/version-5.3/client-api/configuration/querying.mdx index eddc8e8e0e..b099c78cfd 100644 --- a/versioned_docs/version-5.3/client-api/configuration/querying.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/configuration/serialization.mdx b/versioned_docs/version-5.3/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-5.3/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-5.3/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-5.3/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-5.3/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/_creating-document-store-java.mdx b/versioned_docs/version-5.3/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-5.3/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-5.3/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-5.3/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-5.3/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-5.3/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-5.3/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-5.3/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-5.3/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-5.3/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-5.3/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-5.3/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/creating-document-store.mdx b/versioned_docs/version-5.3/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-5.3/client-api/creating-document-store.mdx +++ b/versioned_docs/version-5.3/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index f1060541f7..0000000000 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index b041e66af7..0000000000 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 3426efa1e3..0000000000 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index 545845e219..b9549d42f0 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index d3a82e1653..3f0e2da860 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/api-overview.mdx index 664e6da134..039bd0ab76 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/examples.mdx index f1a5bcecab..4dbdd9514b 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/examples.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 0ebc8ffa28..a7c47c814e 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..e4db04bee5 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..2be5da50f0 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..0a97729fc2 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/api-overview.mdx index 460655150d..e05c87edf4 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-5.3/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/examples.mdx index ca8c2f97c2..d5c631951d 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/examples.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index 2f4bb31103..948b6a10e8 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-5.3/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-5.3/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-5.3/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-5.3/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-5.3/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-5.3/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-5.3/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-5.3/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-5.3/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-5.3/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-5.3/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-5.3/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-5.3/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-5.3/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-5.3/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-5.3/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-5.3/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-5.3/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-5.3/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-5.3/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-5.3/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-5.3/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-5.3/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-5.3/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-5.3/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-5.3/client-api/how-to/handle-document-relationships.mdx index c51cd0e591..8443628d95 100644 --- a/versioned_docs/version-5.3/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-5.3/client-api/how-to/handle-document-relationships.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-5.3/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-5.3/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-5.3/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-5.3/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-5.3/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-5.3/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/net-client-versions.mdx b/versioned_docs/version-5.3/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-5.3/client-api/net-client-versions.mdx +++ b/versioned_docs/version-5.3/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-5.3/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/delete-attachment.mdx index e46c7e8e36..b7570a3112 100644 --- a/versioned_docs/version-5.3/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-5.3/client-api/operations/attachments/delete-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/get-attachment.mdx index c5856fce1a..4dea2e8149 100644 --- a/versioned_docs/version-5.3/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-5.3/client-api/operations/attachments/get-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-5.3/client-api/operations/attachments/put-attachment.mdx index e3ea982729..07e87cb0f8 100644 --- a/versioned_docs/version-5.3/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-5.3/client-api/operations/attachments/put-attachment.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-5.3/client-api/operations/common/delete-by-query.mdx index 40c0818ab2..331c375620 100644 --- a/versioned_docs/version-5.3/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-5.3/client-api/operations/common/delete-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-5.3/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 2139eab165..89924ca1c3 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 8eb75698fb..e5de026d99 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index b05dd86c51..0922b9c087 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/include-compare-exchange.mdx index 504daa4a02..0e3e24afd7 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/overview.mdx index 8c80839bba..2b4ce01f23 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-5.3/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index 0bc62ecb71..e54d296e6f 100644 --- a/versioned_docs/version-5.3/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-5.3/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-5.3/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-5.3/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-5.3/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-5.3/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-5.3/client-api/operations/counters/counter-batch.mdx index 465058670a..9b4dbdc2af 100644 --- a/versioned_docs/version-5.3/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-5.3/client-api/operations/counters/counter-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-5.3/client-api/operations/counters/get-counters.mdx index 153e4049e0..5fbaaf385e 100644 --- a/versioned_docs/version-5.3/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-5.3/client-api/operations/counters/get-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index d98c4cb72b..427c80ccc5 100644 --- a/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index cbc3247c96..618b398e0b 100644 --- a/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-5.3/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 241803adef..ff1a46ab8e 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 76fab69461..4e12d9bf02 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 13391da1a9..8d99d80a54 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index dbbb74bb3e..81f30c05e4 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 8870c1da85..418075a390 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 715c28bc20..e48caa5360 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/add-etl.mdx index b849a0157c..83767b75af 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/get-stats.mdx index 2af9e8b305..9a5eb0560d 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/get-stats.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/get-identities.mdx index b4830fe5bd..f269c0e388 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3e8e9f64cb..f17cb462b1 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/seed-identity.mdx index d6780f54f4..7252a96b13 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 4930f0eb79..0961e85a1b 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index.mdx index 1bcd463a4c..3573589211 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/disable-index.mdx index bde3442b40..ed170f520d 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/enable-index.mdx index 5f0de84e7d..b30e75cbe4 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-errors.mdx index 34761e492b..c4fd99dd69 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-names.mdx index 8d3f50cf6a..9c89cbd2af 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index.mdx index 5dec14fb05..6c48d78278 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-indexes.mdx index 61fdba459f..4a205ceff2 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-terms.mdx index dcdb592ca0..48b840a4a5 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/index-has-changed.mdx index ab3eb1b945..5d85b4fe57 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/put-indexes.mdx index c691b6b356..933fb3115f 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/reset-index.mdx index cc7a1b38e9..533f2a88e9 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-lock.mdx index c148cdc2eb..2d273d3a1c 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-priority.mdx index 4a04c5b204..cdc3320965 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-index.mdx index 4c35b6487b..58198fc92a 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-indexing.mdx index c1cea19f21..400bb702ac 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-index.mdx index c01fe0836b..0cd435f749 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-indexing.mdx index befca12644..0b4aa4a308 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-5.3/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-5.3/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-5.3/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/patching/set-based.mdx b/versioned_docs/version-5.3/client-api/operations/patching/set-based.mdx index 6f08e646dc..876bef8fce 100644 --- a/versioned_docs/version-5.3/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-5.3/client-api/operations/patching/set-based.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/patching/single-document.mdx b/versioned_docs/version-5.3/client-api/operations/patching/single-document.mdx index 6dc6e75272..b41b31d73b 100644 --- a/versioned_docs/version-5.3/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-5.3/client-api/operations/patching/single-document.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/add-database-node.mdx index 173aaebd50..0e2b6b7fc6 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/add-database-node.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/compact-database.mdx index 1da4f1b4dc..90b8264f2e 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/compact-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/create-database.mdx index fb3313d4b2..01e457774f 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-5.3/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-databases-state.mdx index d1d01a84a6..5fd1ae5a24 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-5.3/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/operations/what-are-operations.mdx b/versioned_docs/version-5.3/client-api/operations/what-are-operations.mdx index 2c0688e09d..80544bf561 100644 --- a/versioned_docs/version-5.3/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-5.3/client-api/operations/what-are-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-5.3/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-5.3/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/security/deserialization-security.mdx b/versioned_docs/version-5.3/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-5.3/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-5.3/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index a21600f0c9..0000000000 --- a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,191 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) - key/value items that RavenDB creates and manages automatically to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) - transactions in cluster-wide sessions. - Each document will be associated with its own unique Atomic-Guard item. - -* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. - Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, - which is triggered by changing the document. - -* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to - administer compare-exchange entries explicitly. You can still do that if you wish by - [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - the automatic usage of atomic-guards in a session and defining and managing compare exchange - key/value pairs - [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) - where needed. - * **We strongly recommend not managing atomic-guards manually** unless you _truly_ know what you're doing. - Doing so could cancel RavenDB's ACID transaction guarantees. - -* In this page: - * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) - * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) - * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) - * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - - -## How Atomic Guards Work - -Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. -The Atomic-Guards are managed as follows: - -* __New document__: - A new Atomic-Guard is created when successfully saving a new document. - -* __Existing document that doesn't have an Atomic-Guard__: - A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. - -* __Existing document that already has an Atomic-Guard__: - - * Whenever one session modifies a document that already has an associated Atomic-Guard, - the value of its related Atomic-Guard increases. - This allows RavenDB to detect that changes were made to this document. - - * If other sessions have loaded the document before the version changed, - they will not be able to modify it if trying to save after the first session already saved it, - and a `ConcurrencyException` will be thrown. - - * If the session `SaveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. - Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. - - - -## Atomic Guard Transaction Scope - -* Atomic-Guards are local to the database they were defined on. - -* Since Atomic-Guards are implemented as compare-exchange items, - they are Not externally replicated to another database by any ongoing replication task. - Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Syntax and Usage - -In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, -and then used when two sessions compete on changing the document. - - - -{`using (var session = store.OpenAsyncSession(new SessionOptions - \{ - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - \})) -\{ - await session.StoreAsync(new User(), "users/johndoe"); - await session.SaveChangesAsync(); - // An atomic-guard is now automatically created for the new document "users/johndoe". -\} - -// Open two more cluster-wide sessions -using (var session1 = store.OpenAsyncSession( - new SessionOptions - \{TransactionMode = TransactionMode.ClusterWide\})) -using (var session2 = store.OpenAsyncSession( - new SessionOptions - \{TransactionMode = TransactionMode.ClusterWide\})) -\{ - // The two sessions will load the same document at the same time - var loadedUser1 = await session1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await session2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // Session1 will save changes first, which triggers a change in the - // version number of the associated atomic-guard. - await session1.SaveChangesAsync(); - - // session2.saveChanges() will be rejected with ConcurrencyException - // since session1 already changed the atomic-guard version, - // and session2 saveChanges uses the document version that it had when it loaded the document. - await session2.SaveChangesAsync(); -\} -`} - - - -After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, -in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -The generated Atomic-Guard key name is composed of: - - * The prefix `rvn-atomic` - * The ID of the document that it is associated with - - - -## Disabling Atomic Guards - -To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session -`DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - -In the sample below, the session uses **no Atomic-Guards**. - - -{`using (var session = store.OpenAsyncSession(new SessionOptions - \{ - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - \})) -\{ - await session.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await session.SaveChangesAsync(); -\} -`} - - - - - -* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, - you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) - the required compare exchange key/value pairs. - -* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively - impact ACID transaction guarantees. - -* **Do not remove or edit** Atomic-Guards manually while a session is using them. - A session that is currently using these removed Atomic-Guards will not be able to save - their related documents resulting in an error. - * If you accidentally remove an active Atomic-Guard that is associated with an existing document, - recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. - - - - -## When are Atomic Guards Removed - -Atomic guards expire on the expiration of the documents they are used for and are automatically -removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. - - -Since different cleanup tasks handle the removal of deleted and expired documents -and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed -documents would linger in the compare exchange entries list a short while longer before -they are removed. - -* You do **not** need to remove such Atomic-Guards yourself, they will be removed by - the cleanup task. -* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. - RavenDB will create new Atomic-Guards for such documents, and expire the old ones. - - - - - diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index c3348137ff..0000000000 --- a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,192 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) - key/value items that RavenDB creates and manages automatically to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) - transactions in cluster-wide sessions. - Each document will be associated with its own unique Atomic-Guard item. - -* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. - Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, - which is triggered by changing the document. - -* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to - administer compare-exchange entries explicitly. You can still do that if you wish by - [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - the automatic usage of Atomic-Guards in a session and defining and managing compare exchange - key/value pairs - [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) - where needed. - * **We strongly recommend not managing Atomic-Guards manually** unless you _truly_ know what you're doing. - Doing so could cancel RavenDB's ACID transaction guarantees. - -* In this page: - * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) - * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) - * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) - * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - - -## How Atomic Guards Work - -Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. -The Atomic-Guards are managed as follows: - -* __New document__: - A new Atomic-Guard is created when successfully saving a new document. - -* __Existing document that doesn't have an Atomic-Guard__: - A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. - -* __Existing document that already has an Atomic-Guard__: - - * Whenever one session modifies a document that already has an associated Atomic-Guard, - the value of its related Atomic-Guard increases. - This allows RavenDB to detect that changes were made to this document. - - * If other sessions have loaded the document before the version changed, - they will not be able to modify it if trying to save after the first session already saved it, - and a `ConcurrencyException` will be thrown. - - * If the session `saveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. - Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. - - - -## Atomic Guard Transaction Scope - -* Atomic-Guards are local to the database they were defined on. - -* Since Atomic-Guards are implemented as compare-exchange items, - they are Not externally replicated to another database by any ongoing replication task. - Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Syntax and Usage - -In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, -and then used when two sessions compete on changing the document. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two more cluster-wide sessions -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// The two sessions will load the same document at the same time -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 will save changes first, which triggers a change in the -// version number of the associated atomic-guard. -await session1.saveChanges(); - -// session2.saveChanges() will be rejected with a ClusterTransactionConcurrencyException -// since session1 already changed the atomic-guard version, -// and session2 saveChanges uses the document version that it had when it loaded the document. -await session2.saveChanges(); -`} - - - -After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, -in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -The generated Atomic-Guard key name is composed of: - -* The prefix `rvn-atomic` -* The ID of the document that it is associated with - - - -## Disabling Atomic Guards - -To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session -`disableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - -In the sample below, the session uses **no Atomic-Guards**. - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, - you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) - the required compare exchange key/value pairs. - -* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively - impact ACID transaction guarantees. - -* **Do not remove or edit** Atomic-Guards manually while a session is using them. - A session that is currently using these removed Atomic-Guards will not be able to save - their related documents resulting in an error. - * If you accidentally remove an active Atomic-Guard that is associated with an existing document, - recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. - - - - -## When are Atomic Guards Removed - -Atomic-Guards expire on the expiration of the documents they are used for and are automatically -removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. - - -Since different cleanup tasks handle the removal of deleted and expired documents -and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed -documents would linger in the compare exchange entries list a short while longer before -they are removed. - -* You do **not** need to remove such Atomic-Guards yourself, they will be removed by - the cleanup task. -* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. - RavenDB will create new Atomic-Guards for such documents, and expire the old ones. - - - - - diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/atomic-guards.mdx index 2d99597a49..97044028b9 100644 --- a/versioned_docs/version-5.3/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-5.3/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/compare-exchange.mdx index 3693f7b9bf..d2305f1c22 100644 --- a/versioned_docs/version-5.3/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-5.3/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..810f6510f3 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,191 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) + key/value items that RavenDB creates and manages automatically to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) + transactions in cluster-wide sessions. + Each document will be associated with its own unique Atomic-Guard item. + +* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. + Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, + which is triggered by changing the document. + +* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to + administer compare-exchange entries explicitly. You can still do that if you wish by + [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + the automatic usage of atomic-guards in a session and defining and managing compare exchange + key/value pairs + [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) + where needed. + * **We strongly recommend not managing atomic-guards manually** unless you _truly_ know what you're doing. + Doing so could cancel RavenDB's ACID transaction guarantees. + +* In this page: + * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) + * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) + * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) + * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + + +## How Atomic Guards Work + +Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. +The Atomic-Guards are managed as follows: + +* __New document__: + A new Atomic-Guard is created when successfully saving a new document. + +* __Existing document that doesn't have an Atomic-Guard__: + A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. + +* __Existing document that already has an Atomic-Guard__: + + * Whenever one session modifies a document that already has an associated Atomic-Guard, + the value of its related Atomic-Guard increases. + This allows RavenDB to detect that changes were made to this document. + + * If other sessions have loaded the document before the version changed, + they will not be able to modify it if trying to save after the first session already saved it, + and a `ConcurrencyException` will be thrown. + + * If the session `SaveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. + Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. + + + +## Atomic Guard Transaction Scope + +* Atomic-Guards are local to the database they were defined on. + +* Since Atomic-Guards are implemented as compare-exchange items, + they are Not externally replicated to another database by any ongoing replication task. + Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Syntax and Usage + +In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, +and then used when two sessions compete on changing the document. + + + +{`using (var session = store.OpenAsyncSession(new SessionOptions + \{ + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + \})) +\{ + await session.StoreAsync(new User(), "users/johndoe"); + await session.SaveChangesAsync(); + // An atomic-guard is now automatically created for the new document "users/johndoe". +\} + +// Open two more cluster-wide sessions +using (var session1 = store.OpenAsyncSession( + new SessionOptions + \{TransactionMode = TransactionMode.ClusterWide\})) +using (var session2 = store.OpenAsyncSession( + new SessionOptions + \{TransactionMode = TransactionMode.ClusterWide\})) +\{ + // The two sessions will load the same document at the same time + var loadedUser1 = await session1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await session2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // Session1 will save changes first, which triggers a change in the + // version number of the associated atomic-guard. + await session1.SaveChangesAsync(); + + // session2.saveChanges() will be rejected with ConcurrencyException + // since session1 already changed the atomic-guard version, + // and session2 saveChanges uses the document version that it had when it loaded the document. + await session2.SaveChangesAsync(); +\} +`} + + + +After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, +in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +The generated Atomic-Guard key name is composed of: + + * The prefix `rvn-atomic` + * The ID of the document that it is associated with + + + +## Disabling Atomic Guards + +To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session +`DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + +In the sample below, the session uses **no Atomic-Guards**. + + +{`using (var session = store.OpenAsyncSession(new SessionOptions + \{ + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + \})) +\{ + await session.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await session.SaveChangesAsync(); +\} +`} + + + + + +* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, + you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) + the required compare exchange key/value pairs. + +* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively + impact ACID transaction guarantees. + +* **Do not remove or edit** Atomic-Guards manually while a session is using them. + A session that is currently using these removed Atomic-Guards will not be able to save + their related documents resulting in an error. + * If you accidentally remove an active Atomic-Guard that is associated with an existing document, + recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. + + + + +## When are Atomic Guards Removed + +Atomic guards expire on the expiration of the documents they are used for and are automatically +removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. + + +Since different cleanup tasks handle the removal of deleted and expired documents +and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed +documents would linger in the compare exchange entries list a short while longer before +they are removed. + +* You do **not** need to remove such Atomic-Guards yourself, they will be removed by + the cleanup task. +* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. + RavenDB will create new Atomic-Guards for such documents, and expire the old ones. + + + + + diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..936efaac78 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,192 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic-Guards** are [compare exchange](../../../client-api/operations/compare-exchange/overview.mdx) + key/value items that RavenDB creates and manages automatically to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) + transactions in cluster-wide sessions. + Each document will be associated with its own unique Atomic-Guard item. + +* Atomic-Guards coordinate work between sessions that try to write on a document at the same time. + Saving a document is prevented if another session has incremented the Atomic-Guard Raft index, + which is triggered by changing the document. + +* Prior to the introduction of this feature (in **RavenDB 5.2**), client code had to + administer compare-exchange entries explicitly. You can still do that if you wish by + [disabling](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + the automatic usage of Atomic-Guards in a session and defining and managing compare exchange + key/value pairs + [yourself](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation) + where needed. + * **We strongly recommend not managing Atomic-Guards manually** unless you _truly_ know what you're doing. + Doing so could cancel RavenDB's ACID transaction guarantees. + +* In this page: + * [How Atomic Guards Work](../../../client-api/session/cluster-transaction/atomic-guards.mdx#how-atomic-guards-work) + * [Atomic Guard Transaction Scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-transaction-scope) + * [Syntax and Usage](../../../client-api/session/cluster-transaction/atomic-guards.mdx#syntax-and-usage) + * [Disabling Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are Atomic Guards Removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + + +## How Atomic Guards Work + +Atomic-Guards are created and managed by default __only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)__. +The Atomic-Guards are managed as follows: + +* __New document__: + A new Atomic-Guard is created when successfully saving a new document. + +* __Existing document that doesn't have an Atomic-Guard__: + A new Atomic-Guard is created when modifying an existing document that does not yet have an associated Atomic-Guard. + +* __Existing document that already has an Atomic-Guard__: + + * Whenever one session modifies a document that already has an associated Atomic-Guard, + the value of its related Atomic-Guard increases. + This allows RavenDB to detect that changes were made to this document. + + * If other sessions have loaded the document before the version changed, + they will not be able to modify it if trying to save after the first session already saved it, + and a `ConcurrencyException` will be thrown. + + * If the session `saveChanges()` fails, the entire session is rolled-back and the Atomic-Guard is not created. + Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session. + + + +## Atomic Guard Transaction Scope + +* Atomic-Guards are local to the database they were defined on. + +* Since Atomic-Guards are implemented as compare-exchange items, + they are Not externally replicated to another database by any ongoing replication task. + Learn more in [why compare-exhange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Syntax and Usage + +In the code sample below, an Atomic-Guard is automatically created upon the creation of a new document, +and then used when two sessions compete on changing the document. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two more cluster-wide sessions +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// The two sessions will load the same document at the same time +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 will save changes first, which triggers a change in the +// version number of the associated atomic-guard. +await session1.saveChanges(); + +// session2.saveChanges() will be rejected with a ClusterTransactionConcurrencyException +// since session1 already changed the atomic-guard version, +// and session2 saveChanges uses the document version that it had when it loaded the document. +await session2.saveChanges(); +`} + + + +After running the above example, the Atomic-Guard that was automatically created can be viewed in the Studio, +in the [Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +The generated Atomic-Guard key name is composed of: + +* The prefix `rvn-atomic` +* The ID of the document that it is associated with + + + +## Disabling Atomic Guards + +To **disable** the automatic creation & usage of Atomic-Guards in a session, set the session +`disableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + +In the sample below, the session uses **no Atomic-Guards**. + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +* To enable **ACIDity in cluster-wide transactions** when Atomic-Guards are disabled, + you have to explicitly [set and use](../../../client-api/operations/compare-exchange/overview.mdx) + the required compare exchange key/value pairs. + +* Only disable and edit Atomic-Guards if you truly know what you're doing as it can negatively + impact ACID transaction guarantees. + +* **Do not remove or edit** Atomic-Guards manually while a session is using them. + A session that is currently using these removed Atomic-Guards will not be able to save + their related documents resulting in an error. + * If you accidentally remove an active Atomic-Guard that is associated with an existing document, + recreate or save the document again in a cluster-wide session which will re-create the Atomic-Guard. + + + + +## When are Atomic Guards Removed + +Atomic-Guards expire on the expiration of the documents they are used for and are automatically +removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself. + + +Since different cleanup tasks handle the removal of deleted and expired documents +and the removal of expired Atomic-Guards, it may happen that Atomic-Guards of removed +documents would linger in the compare exchange entries list a short while longer before +they are removed. + +* You do **not** need to remove such Atomic-Guards yourself, they will be removed by + the cleanup task. +* You **can** re-create expired documents whose Atomic-Guards haven't been removed yet. + RavenDB will create new Atomic-Guards for such documents, and expire the old ones. + + + + + diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-5.3/client-api/session/cluster-transaction/overview.mdx index 6787bd6be7..a26704cabc 100644 --- a/versioned_docs/version-5.3/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-5.3/client-api/session/cluster-transaction/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index a71788d72a..1d917bdcf6 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index 302432b734..e4ad373d4e 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index 962e7eeff6..abb4e03518 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-caching.mdx index a72ac682b0..1506a20101 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-tracking.mdx index 1399fe8c0b..49c6ebd8a1 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-5.3/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 3bc0a03a26..e3dd98ad7d 100644 --- a/versioned_docs/version-5.3/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-5.3/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/deleting-entities.mdx b/versioned_docs/version-5.3/client-api/session/deleting-entities.mdx index 0e46a545bd..2f3f6db846 100644 --- a/versioned_docs/version-5.3/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/deleting-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-5.3/client-api/session/how-to/check-if-attachment-exists.mdx index 379619b069..62f1018333 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-5.3/client-api/session/how-to/check-if-document-exists.mdx index f41ee097a2..2e11ba9929 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/check-if-document-exists.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-5.3/client-api/session/how-to/check-if-entity-has-changed.mdx index ec2971af98..5f99c946e2 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-5.3/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 38a0d003d2..fc93d32dce 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-5.3/client-api/session/how-to/clear-a-session.mdx index eacc7ff2e8..8b1812b924 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/clear-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-5.3/client-api/session/how-to/defer-operations.mdx index 5854e379c5..309a2e5034 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/defer-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-5.3/client-api/session/how-to/evict-entity-from-a-session.mdx index 5088e732b3..431fd868ee 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-current-session-node.mdx index 1816a88a7f..b494ad957e 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-current-session-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-change-vector.mdx index b11d1a18b8..96d0b41e34 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-counters.mdx index 18359541bb..7a76778c86 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-counters.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-last-modified.mdx index 9827c320e0..aba3306d9e 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-5.3/client-api/session/how-to/ignore-entity-changes.mdx index c9c6522156..e01e528248 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-5.3/client-api/session/how-to/perform-operations-lazily.mdx index 7d627b5024..fa70ee89c9 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-5.3/client-api/session/how-to/refresh-entity.mdx index 3504bf0854..e4de82eb16 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/refresh-entity.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-5.3/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-5.3/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-5.3/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/loading-entities.mdx b/versioned_docs/version-5.3/client-api/session/loading-entities.mdx index a9115efb39..a9efe7f4d5 100644 --- a/versioned_docs/version-5.3/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/loading-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/opening-a-session.mdx b/versioned_docs/version-5.3/client-api/session/opening-a-session.mdx index 8354581dea..3cb63fa64a 100644 --- a/versioned_docs/version-5.3/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-5.3/client-api/session/opening-a-session.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 77ba83eeda..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,215 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) - ----- - - -## Query the collection (dynamic query) - -* You can make a dynamic query on a collection to find which documents are missing the specified field. - -* Use extension methods `Not` & `WhereExists` that are accessible from [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx). - -* This will either create a new auto-index or add the queried field to an existing auto-index. - Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - - - -__Example__ - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query a static index - -* You can search for documents with missing fields by querying a static index. - -* The index definition must have the following document-fields indexed: - - 1. The field that is suspected to be __missing in some documents__. - - 2. A document-field that __exists in all documents__ in the collection, - (i.e. the _Id_ field, or any other field that is common to all). - Indexing such a field is mandatory so that all documents in the collection will be indexed. - - - -__Example__ - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query by RQL in Studio - -* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause, - first search for a field that __exists__ in every document in the collection, - and then search for the field that __may not exist__ in some of document. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the RQL query. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (Field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index c91513c241..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,170 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) - ----- - - -## Query the collection (dynamic query) - -* You can make a dynamic query on a collection to find which documents are missing the specified field. - -* Use extension methods `not` & `whereExists` that are accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API. - -* This will either create a new auto-index or add the queried field to an existing auto-index. - Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - - - -__Example__ - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query a static index - -* You can search for documents with missing fields by querying a static index. - -* The index definition must have the following document-fields indexed: - - 1. The field that is suspected to be __missing in some documents__. - - 2. A document-field that __exists in all documents__ in the collection, - (i.e. the _id_ field, or any other field that is common to all). - Indexing such a field is mandatory so that all documents in the collection will be indexed. - - - -__Example__ - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - - - -## Query by RQL in Studio - -* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - - -{`from "orders" -where exists("company") and not exists("freight") -`} - - - -* In the `where` clause, - first search for a field that __exists__ in every document in the collection, - and then search for the field that __may not exist__ in some of document. - -![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - -1. **Indexes** - Click to see the Indexes menu. -2. **Query** - Select to open the Query view. -3. **Query editor** - Write the RQL query. -4. **Run Query** - Click or press ctrl+enter to run the query. -5. **Index used** - This is the name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. -6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (Field "Freight" was explicitly removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index ec6956b550..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,991 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You have two options: - - * __Dynamic spatial query__ - Either make a dynamic spatial query on a collection ( __described in this article__ ). - An auto-index will be created by the server. - - * __Spatial index query__ - Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from the Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### Spatial - - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __path__ | `Expression>` | Path to spatial field in an index
(when querying an index) | -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index) | -| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| __clause__ | `Func` | Spatial criteria that will be executed on a given spatial field | - -#### DynamicSpatialFieldFactory - - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| __latitudePath__ / __longitudePath__ / __wktPath__ | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | - -#### SpatialCriteriaFactory - - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `double` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### OrderByDistance - - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -#### OrderByDistanceDescending - - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __path__ | `Expression>` | Path to spatial field in index
(when querying an index) | -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index) | -| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `double` | Used to define a point from which distance will be measured | -| __roundFactor__ | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index 11723f7cb7..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,504 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You have two options: - - * __Dynamic spatial query__ - Either make a dynamic spatial query on a collection ( __described in this article__ ). - An auto-index will be created by the server. - - * __Spatial index query__ - Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from the Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 0cf3ae0b47..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer __similar terms__ from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a __dynamic-query__. - For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into __terms__ that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * __When query has no results__: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * __When looking for alternative terms__: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. __The field name__ - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -__Suggest using__: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| __suggestion__ | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| __builder__ | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -__Builder operations__: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| __fieldName__ | `string` | The index field in which to search for similar terms | -| __path__ | `Expression>` | The index field in which to search for similar terms | -| __term__ | `string` | The term for which to get suggested similar terms | -| __terms__ | `string[]` | List of terms for which to get suggested similar terms | -| __displayName__ | `string` | A custom name for the suggestions result (optional). | -| __options__ | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -__Suggestions options__: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 4ea7647395..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer __similar terms__ from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a __dynamic-query__. - For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into __terms__ that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * __When query has no results__: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * __When looking for alternative terms__: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the __Northwind sample data__, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. __The field name__ - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -__Suggest using__: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| __action__ | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -__Builder operations__: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | The index field in which to search for similar terms | -| __term__ | `string` | The term for which to get suggested similar terms | -| __terms__ | `string[]` | List of terms for which to get suggested similar terms | -| __displayName__ | `string` | A custom name for the suggestions result (optional). | -| __options__ | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -__Suggestions options__: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..f1f89ef8ef --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,215 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) + +---- + + +## Query the collection (dynamic query) + +* You can make a dynamic query on a collection to find which documents are missing the specified field. + +* Use extension methods `Not` & `WhereExists` that are accessible from [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx). + +* This will either create a new auto-index or add the queried field to an existing auto-index. + Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + + + +__Example__ + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query a static index + +* You can search for documents with missing fields by querying a static index. + +* The index definition must have the following document-fields indexed: + + 1. The field that is suspected to be __missing in some documents__. + + 2. A document-field that __exists in all documents__ in the collection, + (i.e. the _Id_ field, or any other field that is common to all). + Indexing such a field is mandatory so that all documents in the collection will be indexed. + + + +__Example__ + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query by RQL in Studio + +* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause, + first search for a field that __exists__ in every document in the collection, + and then search for the field that __may not exist__ in some of document. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the RQL query. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (Field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..91158357a8 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,170 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Query by RQL in Studio](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-by-rql-in-studio) + +---- + + +## Query the collection (dynamic query) + +* You can make a dynamic query on a collection to find which documents are missing the specified field. + +* Use extension methods `not` & `whereExists` that are accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API. + +* This will either create a new auto-index or add the queried field to an existing auto-index. + Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + + + +__Example__ + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query a static index + +* You can search for documents with missing fields by querying a static index. + +* The index definition must have the following document-fields indexed: + + 1. The field that is suspected to be __missing in some documents__. + + 2. A document-field that __exists in all documents__ in the collection, + (i.e. the _id_ field, or any other field that is common to all). + Indexing such a field is mandatory so that all documents in the collection will be indexed. + + + +__Example__ + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + + + +## Query by RQL in Studio + +* You can query for documents with missing fields in the Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + + +{`from "orders" +where exists("company") and not exists("freight") +`} + + + +* In the `where` clause, + first search for a field that __exists__ in every document in the collection, + and then search for the field that __may not exist__ in some of document. + +![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + +1. **Indexes** + Click to see the Indexes menu. +2. **Query** + Select to open the Query view. +3. **Query editor** + Write the RQL query. +4. **Run Query** + Click or press ctrl+enter to run the query. +5. **Index used** + This is the name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. +6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (Field "Freight" was explicitly removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..791e505612 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,991 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You have two options: + + * __Dynamic spatial query__ + Either make a dynamic spatial query on a collection ( __described in this article__ ). + An auto-index will be created by the server. + + * __Spatial index query__ + Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from the Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### Spatial + + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __path__ | `Expression>` | Path to spatial field in an index
(when querying an index) | +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index) | +| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| __clause__ | `Func` | Spatial criteria that will be executed on a given spatial field | + +#### DynamicSpatialFieldFactory + + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| __latitudePath__ / __longitudePath__ / __wktPath__ | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | + +#### SpatialCriteriaFactory + + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `double` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### OrderByDistance + + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +#### OrderByDistanceDescending + + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __path__ | `Expression>` | Path to spatial field in index
(when querying an index) | +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index) | +| __field__ | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `double` | Used to define a point from which distance will be measured | +| __roundFactor__ | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..57d21633b0 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,504 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You have two options: + + * __Dynamic spatial query__ + Either make a dynamic spatial query on a collection ( __described in this article__ ). + An auto-index will be created by the server. + + * __Spatial index query__ + Or, index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)), + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from the Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..527562a055 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer __similar terms__ from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a __dynamic-query__. + For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into __terms__ that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * __When query has no results__: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * __When looking for alternative terms__: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. __The field name__ - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +__Suggest using__: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| __suggestion__ | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| __builder__ | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +__Builder operations__: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| __fieldName__ | `string` | The index field in which to search for similar terms | +| __path__ | `Expression>` | The index field in which to search for similar terms | +| __term__ | `string` | The term for which to get suggested similar terms | +| __terms__ | `string[]` | List of terms for which to get suggested similar terms | +| __displayName__ | `string` | A custom name for the suggestions result (optional). | +| __options__ | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +__Suggestions options__: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..cd1c1eb260 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer __similar terms__ from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a __dynamic-query__. + For getting suggestions with an __index-query__ see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into __terms__ that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * __When query has no results__: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * __When looking for alternative terms__: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the __Northwind sample data__, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest __existing terms__ that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. __The field name__ - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. __The terms__ generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +__Suggest using__: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| __action__ | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +__Builder operations__: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | The index field in which to search for similar terms | +| __term__ | `string` | The term for which to get suggested similar terms | +| __terms__ | `string[]` | List of terms for which to get suggested similar terms | +| __displayName__ | `string` | A custom name for the suggestions result (optional). | +| __options__ | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +__Suggestions options__: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index 57c74c6155..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a __score__. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* __To get the score details__ and see how it was calculated, - you can use `IncludeExplanations` when querying with a [DocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Query with \`DocumentQuery\` -var results = session.Advanced.DocumentQuery() - - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(results[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var results = await asyncSession.Advanced.AsyncDocumentQuery() - - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(results[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the __Query view__ in the Studio. - -* Running a query with `include explanations()` will show an additional __Explanations Tab__. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 9e5b23ad54..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,95 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a __score__. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query __to get the score details__ and see how it was calculated. - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const results = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explenations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const scoreDetails = explanationsResults.explanations[productResults[0].id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the __Query view__ in the Studio. -* Running a query with `include explanations()` will show an additional __Explanations Tab__. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - -<small> __The Explanations object__: </small> - - -{`class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index ad145fbf55..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index b4c6b9da8a..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 389cd336ce..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,97 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..f60bdf1f49 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a __score__. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* __To get the score details__ and see how it was calculated, + you can use `IncludeExplanations` when querying with a [DocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Query with \`DocumentQuery\` +var results = session.Advanced.DocumentQuery() + + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(results[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var results = await asyncSession.Advanced.AsyncDocumentQuery() + + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(results[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the __Query view__ in the Studio. + +* Running a query with `include explanations()` will show an additional __Explanations Tab__. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..f594fc887e --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,95 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a __score__. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query __to get the score details__ and see how it was calculated. + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const results = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explenations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const scoreDetails = explanationsResults.explanations[productResults[0].id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the __Query view__ in the Studio. +* Running a query with `include explanations()` will show an additional __Explanations Tab__. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + +<small> __The Explanations object__: </small> + + +{`class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..416987fcd3 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..2181b57837 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..a92e9ce1f3 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,97 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/include-explanations.mdx index 521eae33e2..a398b3efa5 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/include-explanations.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-5.3/client-api/session/querying/debugging/query-timings.mdx index 7663264dbb..f95a1b302c 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/debugging/query-timings.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/query-vs-document-query.mdx index b5136f5c1e..db01c023aa 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/document-query/what-is-document-query.mdx index d7a4d4ff71..ac20723481 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-count-query-results.mdx index 5318fd5abb..004f7ead31 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-count-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-customize-query.mdx index aad41a1873..ae69eb4255 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-customize-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-field.mdx index 22bcfb442c..0bfcf6f7b4 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index e99c7c48ec..30a68f9ad5 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-get-query-statistics.mdx index 898ccdc414..6fed1cfc62 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-make-a-spatial-query.mdx index d38261b5fe..fe60279a62 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-a-faceted-search.mdx index aedcc244ca..e4b8a706e0 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-group-by-query.mdx index ea5c1cd887..c39cffd687 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-queries-lazily.mdx index 12efb93d4d..7a56389fb9 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-project-query-results.mdx index aef01d210b..b469e21d78 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-project-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-query.mdx index 9c593fb421..87039948b8 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-use-intersect.mdx index f650d10408..d4df3a9377 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-use-intersect.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-use-morelikethis.mdx index 0983bcd524..e5bd39dbb3 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-5.3/client-api/session/querying/how-to-work-with-suggestions.mdx index f21a0074f3..bd02108b2e 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/sort-query-results.mdx index e69d03116c..a6ca4d0210 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/sort-query-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index 90790d2ef7..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __path__ | `Expression>` | Path to the field that contains the searched terms to highlight. | -| __fragmentLength__ | int | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | int | Maximum number of text fragments that will be returned. | -| __options__ | `HighlightingOptions` | Customizing options. | -| __highlightings__ | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -__Highlighting options__: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __GroupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __PreTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __PostTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__Highlightings object__: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| __FieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __ResultIndents__ | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| __GetFragments__ | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/boost-search-results.mdx index 05616535dd..459d7e1e2b 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..4f74546abc --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __path__ | `Expression>` | Path to the field that contains the searched terms to highlight. | +| __fragmentLength__ | int | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | int | Maximum number of text fragments that will be returned. | +| __options__ | `HighlightingOptions` | Customizing options. | +| __highlightings__ | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +__Highlighting options__: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __GroupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __PreTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __PostTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__Highlightings object__: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| __FieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __ResultIndents__ | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| __GetFragments__ | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-5.3/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/ends-with-query.mdx index c2535d37a8..0bb4e0e597 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/exact-match-query.mdx index 0548f020e2..ec244ac053 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/full-text-search.mdx index 78ac594a53..f54a6e4e62 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/full-text-search.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/fuzzy-search.mdx index 9e195d4290..e146956ec5 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/highlight-query-results.mdx index d890b4d123..2003d34238 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/proximity-search.mdx index 12a1a3ce5d..091ea6ad65 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/proximity-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/starts-with-query.mdx index f5f965cf18..f139ef9545 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-5.3/client-api/session/querying/text-search/using-regex.mdx index a9dae3e72c..afc9483db5 100644 --- a/versioned_docs/version-5.3/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-5.3/client-api/session/querying/text-search/using-regex.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/saving-changes.mdx b/versioned_docs/version-5.3/client-api/session/saving-changes.mdx index 31d3090030..c6d8b6b7b2 100644 --- a/versioned_docs/version-5.3/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-5.3/client-api/session/saving-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/storing-entities.mdx b/versioned_docs/version-5.3/client-api/session/storing-entities.mdx index c8409107c9..fb5d92b576 100644 --- a/versioned_docs/version-5.3/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/storing-entities.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/updating-entities.mdx b/versioned_docs/version-5.3/client-api/session/updating-entities.mdx index d32cd550a0..51396db0de 100644 --- a/versioned_docs/version-5.3/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-5.3/client-api/session/updating-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-5.3/client-api/session/what-is-a-session-and-how-does-it-work.mdx index e27431ce62..e4170c24e5 100644 --- a/versioned_docs/version-5.3/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-5.3/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-5.3/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-5.3/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-5.3/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/setting-up-default-database.mdx b/versioned_docs/version-5.3/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-5.3/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-5.3/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-5.3/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-5.3/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-5.3/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-5.3/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-5.3/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/client-api/what-is-a-document-store.mdx b/versioned_docs/version-5.3/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-5.3/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-5.3/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-5.3/document-extensions/attachments/copying-moving-renaming.mdx index b9774d0444..65484c9d78 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/deleting.mdx b/versioned_docs/version-5.3/document-extensions/attachments/deleting.mdx index 6259980cd3..3a916d6185 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/deleting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/indexing.mdx b/versioned_docs/version-5.3/document-extensions/attachments/indexing.mdx index 952c7c850c..effc2fb8a1 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/loading.mdx b/versioned_docs/version-5.3/document-extensions/attachments/loading.mdx index 9df0597641..13d7ce3ad5 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/storing.mdx b/versioned_docs/version-5.3/document-extensions/attachments/storing.mdx index 63f3d6f602..f9646cbe1f 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/storing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-5.3/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-5.3/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-5.3/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-5.3/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-5.3/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-5.3/document-extensions/counters/counters-and-other-features.mdx index d567f37006..217b2590a4 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/counters-and-other-features.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-5.3/document-extensions/counters/create-or-modify.mdx index 5e8c29ec4a..8f8d71dfef 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/create-or-modify.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/delete.mdx b/versioned_docs/version-5.3/document-extensions/counters/delete.mdx index 949fb2feed..d1e2ffe8a1 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/indexing.mdx b/versioned_docs/version-5.3/document-extensions/counters/indexing.mdx index 3631c6ba3a..fc79f90af0 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/indexing.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/overview.mdx b/versioned_docs/version-5.3/document-extensions/counters/overview.mdx index bf20ec9bcd..50c52e0ffe 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-5.3/document-extensions/counters/retrieve-counter-values.mdx index acd7025f97..669bcfbff9 100644 --- a/versioned_docs/version-5.3/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-5.3/document-extensions/counters/retrieve-counter-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 610bebb32b..0000000000 --- a/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/configure-revisions.mdx index c5e0fbb51d..d8375d935e 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index cb3c2bbc37..a2d1276e65 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/get-revisions.mdx index 5bea829544..d590b4bdec 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/overview.mdx index d8e42b24cf..53eb593412 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/counting.mdx index f346ff4b20..e0b9f7546a 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/counting.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/including.mdx index 6dc29aa46e..8101db3a41 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/including.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/loading.mdx index 4c0a5db2b1..5615bddebd 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/client-api/session/loading.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..2e366627d8 --- /dev/null +++ b/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-5.3/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-5.3/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-5.3/document-extensions/revisions/revisions-and-other-features.mdx index 3f6121f7a9..e4ba8ab65a 100644 --- a/versioned_docs/version-5.3/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-5.3/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-5.3/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-5.3/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-5.3/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-5.3/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-5.3/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-5.3/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-5.3/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-5.3/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-5.3/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-5.3/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-5.3/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_index-query-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_index-query-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_query-result-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_query-result-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/_stream-result-csharp.mdx b/versioned_docs/version-5.3/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-5.3/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-5.3/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-5.3/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-5.3/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/counters-batch-command-data.mdx b/versioned_docs/version-5.3/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-5.3/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/delete-command-data.mdx b/versioned_docs/version-5.3/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-5.3/glossary/delete-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-5.3/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-5.3/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/index-query.mdx b/versioned_docs/version-5.3/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-5.3/glossary/index-query.mdx +++ b/versioned_docs/version-5.3/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/move-attachment-command-data.mdx b/versioned_docs/version-5.3/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-5.3/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/patch-command-data.mdx b/versioned_docs/version-5.3/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-5.3/glossary/patch-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/put-command-data.mdx b/versioned_docs/version-5.3/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-5.3/glossary/put-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-5.3/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-5.3/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.3/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/query-result.mdx b/versioned_docs/version-5.3/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-5.3/glossary/query-result.mdx +++ b/versioned_docs/version-5.3/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/stream-query-statistics.mdx b/versioned_docs/version-5.3/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-5.3/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-5.3/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-5.3/glossary/stream-result.mdx b/versioned_docs/version-5.3/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-5.3/glossary/stream-result.mdx +++ b/versioned_docs/version-5.3/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index a65d3ec381..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,206 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Use the indexing `Recurse` method to recurse through the layers of a hierarchical document -and index its elements. - -* In this Page: - * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) - - -## Hierarchical Data - -One of the significant advantages offered by document databases is their tendency not to force -limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: -take, for example, the commonly-used **Comment thread**, implemented using objects such as: - - -{`private class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Comments can be left recursively - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments -to its Comments field. And readers of these comments can reply with comments of their own, creating -a recursive hierarchical structure. - -`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of -comments left by various authors. - -`BlogPosts/1-A`: - - -{`\{ - "Author ": "John", - "Comments": [ - \{ - "Author": "Moon", - "Comments": [ - \{ - "Author": "Bob" - \}, - \{ - "Author": "Adel", - "Comments": \{ - "Author": "Moon" - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Indexing Hierarchical Data - -To index the elements of a hierarchical structure like the one demonstrated above, -use RavenDB's `Recurse` method. - -In the sample below, we use `Recurse` to go through comments in the post thread -and index them by their authors. - - - -{`private class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class Result - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new Result - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" - } - })); -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - return recurse(blogpost, x => x.Comments).map(function (comment) { - if (comment.Author != null) { - return { - Authors: comment.Author - }; - } - }); - });" - }; - } -} -`} - - - -### Querying the created index - -* The index we created can be queried using code. - - - -{`IList results = session - .Query() - .Where(x => x.Authors.Any(a => a == "John")) - .OfType() - .ToList(); -`} - - - - -{`IList results = session - .Advanced - .DocumentQuery() - .WhereEquals("Authors", "John") - .ToList(); -`} - - - - -* The index can also be queried using Studio. - - * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) - view to define and query the index. - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) - indexed by the `Recurse` method. - - !["Query View"](./assets/query-view.png) - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.3/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index be4fe4447a..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,599 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following __Classes__ and __Sample Data__: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - - - __The index__: - - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - __The index-entries__: - -![Simple - index-entries](./assets/indexing-nested-data-1.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - The index has a single index-entry per document (3 entries in this example). - -4. The index-field contains a collection of ALL nested values from the document. - e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: - `{"black", "blue", "red"}` - __Querying the index__: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - __When to use__: - -* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - -* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - -* To address this, you must use a __Fanout index__ - as described below. - - - -## Fanout index - Multiple index-entries per document - - - - __What is a Fanout index__: - -* A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - -* The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - - - - - - __Fanout index - Map index example__: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - __The index-entries__: - -![Fanout - index-entries](./assets/indexing-nested-data-2.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - Each index-entry corresponds to an inner item in the TShirt list. - -4. In this example, the total number of index-entries is __12__, - which is the total number of inner items in the TShirt list in all __3__ documents in the collection. - - - - - - __Fanout index - Map-Reduce index example__: - -* The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - - - - - - __Fanout index - Performance hints__: - -* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - -* When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. - -* You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - -* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -* Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - - - - - - __Fanout index - Paging__: - -* A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - -* When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - -* __To overcome this when paging results__, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - -* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-5.3/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.3/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index 608e53adcb..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,420 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following __Classes__ and __Sample Data__: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - - - __The index__: - - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - - __The index-entries__: - -![Simple - index-entries](./assets/indexing-nested-data-1.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - The index has a single index-entry per document (3 entries in this example). - -4. The index-field contains a collection of ALL nested values from the document. - e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: - `{"black", "blue", "red"}` - __Querying the index__: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - __When to use__: - -* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - -* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - -* To address this, you must use a __Fanout index__ - as described below. - - - -## Fanout index - Multiple index-entries per document - - - - __What is a Fanout index__: - -* A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - -* The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - - - - - - __Fanout index - Map index example__: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - __The index-entries__: - -![Fanout - index-entries](./assets/indexing-nested-data-2.png) - -1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - -2. Check option: _Show raw index-entries instead of Matching documents_. - -3. Each row represents an __index-entry__. - Each index-entry corresponds to an inner item in the TShirt list. - -4. In this example, the total number of index-entries is __12__, - which is the total number of inner items in the TShirt list in all __3__ documents in the collection. - - - - - - __Fanout index - Map-Reduce index example__: - -* The fanout index concept applies to map-reduce indexes as well: - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - - - - - - __Fanout index - Performance hints__: - -* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - -* When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. - -* You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - -* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -* Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - - - - - - __Fanout index - Paging__: - -* A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - -* When making a fanout index query that should return full documents (without projecting results), - then in this case, the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - -* __To overcome this when paging results__, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - -* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index c94e8138c2..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index c050af5304..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. - -For example, let's assume that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". - -If we wanted to index cats by name, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - -Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index like this one: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.3/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index a1e6ff4d41..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,468 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, __documents can reference other documents__. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a __Related Document__. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - -![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -__What is tracked__: - -* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -__The documents__: - - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -__The index__: - -* This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -__What is tracked__: - -* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. - Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -__The query__: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was __first indexed__ when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the __indexed collection__ will trigger re-indexing. - -* Any such change done on any document in the __indexed related documents__ will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.3/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.3/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 504fe94ea4..0000000000 --- a/versioned_docs/version-5.3/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, __documents can reference other documents__. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a __Related Document__. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - -![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -__What is tracked__: - -* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -__The query__: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -__The documents__: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -__The index__: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -__The query__: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -__What is tracked__: - -* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. - Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -__The index__: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -__The query__: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was __first indexed__ when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the __indexed collection__ will trigger re-indexing. - -* Any such change done on any document in the __indexed related documents__ will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.3/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 3e1a4a1693..0000000000 --- a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,574 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'Size' use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents with some 'LastName' use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'ProductType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "Name": "SomeName", - "Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's PropName __value__. - e.g. 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.3/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index f1892d11b3..0000000000 --- a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,500 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -__The query__: - -* To get all documents with some 'lastName' use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName __value__. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.3/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index c568184f2b..0000000000 --- a/versioned_docs/version-5.3/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with __dynamic-index-fields__. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -__The document__: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -__The index__: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field __key__. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -__The query__: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection __without__ needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -__The document__: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -__The index__: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field __key__. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -__The document__: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -__The index__: - -* The following index will index the __value__ of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index __values__ from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -__The document__: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -__The index__: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName __value__. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -__The query__: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.3/indexes/boosting.mdx b/versioned_docs/version-5.3/indexes/boosting.mdx index 5db484d2e0..fdae10ce48 100644 --- a/versioned_docs/version-5.3/indexes/boosting.mdx +++ b/versioned_docs/version-5.3/indexes/boosting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/_boosting-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_boosting-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_boosting-java.mdx b/versioned_docs/version-5.3/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_boosting-java.mdx rename to versioned_docs/version-5.3/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_boosting-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-5.3/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-5.3/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_extending-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-basics-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..185c74ef37 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,206 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Use the indexing `Recurse` method to recurse through the layers of a hierarchical document +and index its elements. + +* In this Page: + * [Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Indexing Hierarchical Data](../indexes/indexing-hierarchical-data.mdx#indexing-hierarchical-data) + + +## Hierarchical Data + +One of the significant advantages offered by document databases is their tendency not to force +limits upon data structuring. **Hierarchical data structures** demonstrate this quality beautifully: +take, for example, the commonly-used **Comment thread**, implemented using objects such as: + + +{`private class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Comments can be left recursively + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure, can add `BlogPostComment` comments +to its Comments field. And readers of these comments can reply with comments of their own, creating +a recursive hierarchical structure. + +`BlogPosts/1-A`, for example, is a blog entry posted by John, that contains several layers of +comments left by various authors. + +`BlogPosts/1-A`: + + +{`\{ + "Author ": "John", + "Comments": [ + \{ + "Author": "Moon", + "Comments": [ + \{ + "Author": "Bob" + \}, + \{ + "Author": "Adel", + "Comments": \{ + "Author": "Moon" + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Indexing Hierarchical Data + +To index the elements of a hierarchical structure like the one demonstrated above, +use RavenDB's `Recurse` method. + +In the sample below, we use `Recurse` to go through comments in the post thread +and index them by their authors. + + + +{`private class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class Result + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new Result + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" + } + })); +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + return recurse(blogpost, x => x.Comments).map(function (comment) { + if (comment.Author != null) { + return { + Authors: comment.Author + }; + } + }); + });" + }; + } +} +`} + + + +### Querying the created index + +* The index we created can be queried using code. + + + +{`IList results = session + .Query() + .Where(x => x.Authors.Any(a => a == "John")) + .OfType() + .ToList(); +`} + + + + +{`IList results = session + .Advanced + .DocumentQuery() + .WhereEquals("Authors", "John") + .ToList(); +`} + + + + +* The index can also be queried using Studio. + + * Use Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) + view to define and query the index. + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * Use the **Query** view to see the results and the list of [terms](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view---actions) + indexed by the `Recurse` method. + + !["Query View"](../assets/query-view.png) + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-hierarchical-data-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-hierarchical-data-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..927d354489 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,599 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following __Classes__ and __Sample Data__: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + + + __The index__: + + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + __The index-entries__: + +![Simple - index-entries](../assets/indexing-nested-data-1.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + The index has a single index-entry per document (3 entries in this example). + +4. The index-field contains a collection of ALL nested values from the document. + e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: + `{"black", "blue", "red"}` + __Querying the index__: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + __When to use__: + +* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + +* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + +* To address this, you must use a __Fanout index__ - as described below. + + + +## Fanout index - Multiple index-entries per document + + + + __What is a Fanout index__: + +* A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + +* The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + + + + + + __Fanout index - Map index example__: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + __The index-entries__: + +![Fanout - index-entries](../assets/indexing-nested-data-2.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + Each index-entry corresponds to an inner item in the TShirt list. + +4. In this example, the total number of index-entries is __12__, + which is the total number of inner items in the TShirt list in all __3__ documents in the collection. + + + + + + __Fanout index - Map-Reduce index example__: + +* The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + + + + + + __Fanout index - Performance hints__: + +* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + +* When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. + +* You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + +* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +* Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + + + + + + __Fanout index - Paging__: + +* A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + +* When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + +* __To overcome this when paging results__, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + +* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + + + diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..cba7f70a7a --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,420 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following __Classes__ and __Sample Data__: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + + + __The index__: + + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + + __The index-entries__: + +![Simple - index-entries](../assets/indexing-nested-data-1.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + The index has a single index-entry per document (3 entries in this example). + +4. The index-field contains a collection of ALL nested values from the document. + e.g. The third __index-entry__ has the following values in the _Colors_ __index-field__: + `{"black", "blue", "red"}` + __Querying the index__: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + __When to use__: + +* This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + +* However, due to the way the index-entries are generated, this index __cannot__ provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + +* To address this, you must use a __Fanout index__ - as described below. + + + +## Fanout index - Multiple index-entries per document + + + + __What is a Fanout index__: + +* A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + +* The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + + + + + + __Fanout index - Map index example__: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + __The index-entries__: + +![Fanout - index-entries](../assets/indexing-nested-data-2.png) + +1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + +2. Check option: _Show raw index-entries instead of Matching documents_. + +3. Each row represents an __index-entry__. + Each index-entry corresponds to an inner item in the TShirt list. + +4. In this example, the total number of index-entries is __12__, + which is the total number of inner items in the TShirt list in all __3__ documents in the collection. + + + + + + __Fanout index - Map-Reduce index example__: + +* The fanout index concept applies to map-reduce indexes as well: + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + + + + + + __Fanout index - Performance hints__: + +* Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + +* When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a __High indexing fanout ratio__ alert in the Studio notification center. + +* You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + +* So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +* Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + + + + + + __Fanout index - Paging__: + +* A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + +* When making a fanout index query that should return full documents (without projecting results), + then in this case, the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + +* __To overcome this when paging results__, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + +* Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + + + diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..a2a2669e17 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,150 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..df6b2cb321 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, RavenDB indexes operate only on a specific entity type, or a `Collection`, that ignores the inheritance hierarchy. + +For example, let's assume that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +If we saved a `Cat`, it would have a collection set to "Cats" and if we saved a `Dog`, it would be in collection "Dogs". + +If we wanted to index cats by name, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + +Although it works, each index would only give us results for the animal it has been defined on. But what if we wanted to query across all animals? + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index like this one: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`, like this: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a768088f06 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,468 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, __documents can reference other documents__. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a __Related Document__. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + +![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +__What is tracked__: + +* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +__The documents__: + + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +__The index__: + +* This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +__What is tracked__: + +* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. + Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +__The query__: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was __first indexed__ when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the __indexed collection__ will trigger re-indexing. + +* Any such change done on any document in the __indexed related documents__ will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.3/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..48dd6a0f6d --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, __documents can reference other documents__. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either __Tracked__ or __Not-Tracked__. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a __Related Document__. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + +![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +__What is tracked__: + +* Both the documents from the __indexed collection__ and the __indexed related documents__ are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +__The query__: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +__The documents__: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +__The index__: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +__The query__: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* __Re-indexing__ will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +__What is tracked__: + +* Only the documents from the __indexed collection__ are tracked for changes and can trigger re-indexing. + Any change done to any document in the __indexed related documents__ will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +__The index__: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +__The query__: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was __first indexed__ when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* __Re-indexing__ will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the __indexed collection__ will trigger re-indexing. + +* Any such change done on any document in the __indexed related documents__ will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.3/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-5.3/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-5.3/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_stale-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-5.3/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-5.3/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_using-analyzers-java.mdx b/versioned_docs/version-5.3/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-5.3/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..7d94f57de6 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,574 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'Size' use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents with some 'LastName' use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'ProductType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "Name": "SomeName", + "Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's PropName __value__. + e.g. 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..fa1a55a5ab --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,500 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +__The query__: + +* To get all documents with some 'lastName' use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName __value__. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..9c55ce9551 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with __dynamic-index-fields__. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +__The document__: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +__The index__: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field __key__. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +__The query__: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection __without__ needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +__The document__: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +__The index__: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field __key__. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the __basic concept__ of creating a dynamic-index-field from the __value__ of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +__The document__: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +__The index__: + +* The following index will index the __value__ of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index __values__ from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +__The document__: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +__The index__: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName __value__. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +__The query__: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the __Terms View__. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.3/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_using-term-vectors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-term-vectors-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_using-term-vectors-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-5.3/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-5.3/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.3/indexes/content/_what-are-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_what-are-indexes-csharp.mdx rename to versioned_docs/version-5.3/indexes/content/_what-are-indexes-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-5.3/indexes/content/_what-are-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_what-are-indexes-java.mdx rename to versioned_docs/version-5.3/indexes/content/_what-are-indexes-java.mdx diff --git a/versioned_docs/version-5.3/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.3/indexes/content/_what-are-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/_what-are-indexes-nodejs.mdx rename to versioned_docs/version-5.3/indexes/content/_what-are-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-5.3/indexes/converting-to-json-and-accessing-metadata.mdx index dce433b43d..99bdca1adb 100644 --- a/versioned_docs/version-5.3/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-5.3/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/creating-and-deploying.mdx b/versioned_docs/version-5.3/indexes/creating-and-deploying.mdx index 1397f3eb69..1f97347e67 100644 --- a/versioned_docs/version-5.3/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-5.3/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/extending-indexes.mdx b/versioned_docs/version-5.3/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-5.3/indexes/extending-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-basics.mdx b/versioned_docs/version-5.3/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-5.3/indexes/indexing-basics.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-5.3/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-5.3/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-5.3/indexes/indexing-hierarchical-data.mdx index 6993053cbe..30fb151b58 100644 --- a/versioned_docs/version-5.3/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-hierarchical-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-5.3/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-5.3/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-nested-data.mdx b/versioned_docs/version-5.3/indexes/indexing-nested-data.mdx index bc3310befc..5752230323 100644 --- a/versioned_docs/version-5.3/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-nested-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-5.3/indexes/indexing-polymorphic-data.mdx index a74cc86adf..6036c211db 100644 --- a/versioned_docs/version-5.3/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-polymorphic-data.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-related-documents.mdx b/versioned_docs/version-5.3/indexes/indexing-related-documents.mdx index e28934ff30..343854acdd 100644 --- a/versioned_docs/version-5.3/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-related-documents.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/indexing-spatial-data.mdx b/versioned_docs/version-5.3/indexes/indexing-spatial-data.mdx index 201f538486..9f7cdef92a 100644 --- a/versioned_docs/version-5.3/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-5.3/indexes/indexing-spatial-data.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/javascript-indexes.mdx b/versioned_docs/version-5.3/indexes/javascript-indexes.mdx index d120b3bc12..70bed49b28 100644 --- a/versioned_docs/version-5.3/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/javascript-indexes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; diff --git a/versioned_docs/version-5.3/indexes/map-indexes.mdx b/versioned_docs/version-5.3/indexes/map-indexes.mdx index ebdf82799c..92d33a920d 100644 --- a/versioned_docs/version-5.3/indexes/map-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/map-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/map-reduce-indexes.mdx b/versioned_docs/version-5.3/indexes/map-reduce-indexes.mdx index 0c1f056942..9ad5b42389 100644 --- a/versioned_docs/version-5.3/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/map-reduce-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/multi-map-indexes.mdx b/versioned_docs/version-5.3/indexes/multi-map-indexes.mdx index b369bf0735..42bc8284c2 100644 --- a/versioned_docs/version-5.3/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/multi-map-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; diff --git a/versioned_docs/version-5.3/indexes/number-type-conversion.mdx b/versioned_docs/version-5.3/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-5.3/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-5.3/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 83ff4136a7..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1101 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - - - -__Facets definition__: -* Define a list of facets by which to aggregate the data. - -* There are two __Facet types__: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - - - - - - -__Query the index for facets results__: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - - - - - - -__Query results__: -* __Query results__ are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - - - -__Query further__: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - - - -__Facets definition__: -* __Options__ are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - - - - - - -__Query the index for facets results__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - - - -## Facets - Aggregations - - - -__Facets definition__: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - - - - - - -__Query the index for facets results__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - - - -## Storing facets definition in a document - - - - - -__Define and store facets in a document__: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -__Query using facets from document__: - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| __facets__ | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| __builder__ | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } - public FacetOptions Options { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -__Fluent API builder methods__: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | The index-field to use for the facet | -| __path__ | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| __displayName__ | string | If set, results of a facet will be returned under this name | -| __options__ | `FacetOptions` | Non-default options to use in the facet definition | - -__Options__: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| __TermSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| __Start__ | int | The position from which to send items (how many to skip) | -| __PageSize__ | int | Number of items to return | -| __IncludeRemainingTerms__ | bool | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-5.3/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index df22445cdb..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-5.3/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 74eb0c0698..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,924 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -__Facets definition__: -* Define a list of facets by which to aggregate the data. - -* There are two __Facet types__: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -__Query the index for facets results__: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -__Query results__: -* __Query results__ are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -__Query further__: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -__Facets definition__: -* __Options__ are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -__Query the index for facets results__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -__Facets definition__: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -__Query the index for facets results__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -__Query results__: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -__Define and store facets in a document__: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -__Query using facets from document__: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| __...facet__ | `FacetBase[]` | List containing `FacetBase` implementations. | -| __action__ / __builder__ | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -__builder methods__: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | The index-field to use for the facet | -| __path__ | string | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| __displayName__ | string | If set, results of a facet will be returned under this name | -| __options__ | `FacetOptions` | Non-default options to use in the facet definition | - -__Options__: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| __termSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| __start__ | number | The position from which to send items (how many to skip) | -| __pageSize__ | number | Number of items to return | -| __includeRemainingTerms__ | boolean | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index ac51423559..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,790 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - - * Optimizes bandwidth usage by reducing data transfer between the server and client. - * Prevents delays in response times caused by sending too much data over the network. - * Avoids high memory consumption when dealing with numerous documents. - * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_paging-java.mdx b/versioned_docs/version-5.3/indexes/querying/_paging-java.mdx deleted file mode 100644 index 9fe38f178f..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,302 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -### Basic paging - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -### Find total results count when paging - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -* See the following examples: -__A projection query with Distinct__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -__Querying a Fanout index__: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 5fa0770eab..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,408 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* __Paging__: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* __Default page size__: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* __Performance__: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* __Paging policy__: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - - - -__Retrieve a specific page__: - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - - - - - -__Page through all results__: - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - - -## Paging and performance -__Better performance__: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -__Performance hints__: - -* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -* See the following examples: - - - -__A projection query with Distinct__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - - - - - -__Querying a Fanout index__: - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_spatial-java.mdx b/versioned_docs/version-5.3/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index 1dafeb76fa..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,609 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions, and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the __index definition__. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -__Increased indexing time__: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. __The index-field name__ - as defined in the index definition. - In this example the field name is `ProductName`. - -2. __The terms__ that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 2435c4e1f5..0000000000 --- a/versioned_docs/version-5.3/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,342 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions, and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the __index definition__. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -__Increased indexing time__: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the __Northwind sample data__, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. __The index-field name__ - as defined in the index definition. - In this example the field name is `ProductName`. - -2. __The terms__ that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for single term - -Based on the __Northwind sample data__, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.3/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_distinct-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..1ff5577efb --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1101 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + + + +__Facets definition__: +* Define a list of facets by which to aggregate the data. + +* There are two __Facet types__: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + + + + + + +__Query the index for facets results__: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + + + + + + +__Query results__: +* __Query results__ are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + + + +__Query further__: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + + + +__Facets definition__: +* __Options__ are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + + + + + + +__Query the index for facets results__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + + + +## Facets - Aggregations + + + +__Facets definition__: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + + + + + + +__Query the index for facets results__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + + + +## Storing facets definition in a document + + + + + +__Define and store facets in a document__: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +__Query using facets from document__: + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| __facets__ | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| __builder__ | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } + public FacetOptions Options { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +__Fluent API builder methods__: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | The index-field to use for the facet | +| __path__ | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| __displayName__ | string | If set, results of a facet will be returned under this name | +| __options__ | `FacetOptions` | Non-default options to use in the facet definition | + +__Options__: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| __TermSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| __Start__ | int | The position from which to send items (how many to skip) | +| __PageSize__ | int | Number of items to return | +| __IncludeRemainingTerms__ | bool | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..4ec998bf09 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..7d5cbe3663 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,924 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* In order to make a faceted search, __a static-index must be defined__ for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +__Facets definition__: +* Define a list of facets by which to aggregate the data. + +* There are two __Facet types__: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +__Query the index for facets results__: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +__Query results__: +* __Query results__ are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +__Query further__: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +__Facets definition__: +* __Options__ are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +__Query the index for facets results__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +__Facets definition__: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +__Query the index for facets results__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +__Query results__: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +__Define and store facets in a document__: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +__Query using facets from document__: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| __facet__ | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| __...facet__ | `FacetBase[]` | List containing `FacetBase` implementations. | +| __action__ / __builder__ | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| __facetSetupDocumentId__ | string | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +__builder methods__: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | The index-field to use for the facet | +| __path__ | string | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| __displayName__ | string | If set, results of a facet will be returned under this name | +| __options__ | `FacetOptions` | Non-default options to use in the facet definition | + +__Options__: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| __termSortMode__ | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| __start__ | number | The position from which to send items (how many to skip) | +| __pageSize__ | number | Number of items to return | +| __includeRemainingTerms__ | boolean | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_filtering-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_intersection-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..2f33d5d05b --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,790 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + + * Optimizes bandwidth usage by reducing data transfer between the server and client. + * Prevents delays in response times caused by sending too much data over the network. + * Avoids high memory consumption when dealing with numerous documents. + * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..b48ee81dfa --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,302 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +### Basic paging + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +### Find total results count when paging + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +* See the following examples: +__A projection query with Distinct__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +__Querying a Fanout index__: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..a2335739f0 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,408 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* __Paging__: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* __Default page size__: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* __Performance__: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* __Paging policy__: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + + + +__Retrieve a specific page__: + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + + + + + +__Page through all results__: + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + + +## Paging and performance +__Better performance__: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +__Performance hints__: + +* By default, if the number of returned results exceeds __2048__, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than __0__, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +* See the following examples: + + + +__A projection query with Distinct__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + + + + + +__Querying a Fanout index__: + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_projections-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_projections-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_query-index-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_sorting-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.3/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-5.3/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..840a75a167 --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,609 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the __index definition__. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +__Increased indexing time__: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. __The index-field name__ - as defined in the index definition. + In this example the field name is `ProductName`. + +2. __The terms__ that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-5.3/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.3/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-5.3/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-5.3/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-5.3/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..5cc498b16f --- /dev/null +++ b/versioned_docs/version-5.3/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,342 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to this article, please refer to [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the __index definition__. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +__Increased indexing time__: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the __Northwind sample data__, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. __The index-field name__ - as defined in the index definition. + In this example the field name is `ProductName`. + +2. __The terms__ that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for single term + +Based on the __Northwind sample data__, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.3/indexes/querying/distinct.mdx b/versioned_docs/version-5.3/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-5.3/indexes/querying/distinct.mdx +++ b/versioned_docs/version-5.3/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/exploration-queries.mdx b/versioned_docs/version-5.3/indexes/querying/exploration-queries.mdx index 6237fde72a..95cef012da 100644 --- a/versioned_docs/version-5.3/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-5.3/indexes/querying/exploration-queries.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/faceted-search.mdx b/versioned_docs/version-5.3/indexes/querying/faceted-search.mdx index d8f05ac087..5bc6531f85 100644 --- a/versioned_docs/version-5.3/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-5.3/indexes/querying/faceted-search.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/filtering.mdx b/versioned_docs/version-5.3/indexes/querying/filtering.mdx index 8f6d6600e6..22a9e5f917 100644 --- a/versioned_docs/version-5.3/indexes/querying/filtering.mdx +++ b/versioned_docs/version-5.3/indexes/querying/filtering.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/highlighting.mdx b/versioned_docs/version-5.3/indexes/querying/highlighting.mdx index 98ed24c787..30404650cd 100644 --- a/versioned_docs/version-5.3/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-5.3/indexes/querying/highlighting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/intersection.mdx b/versioned_docs/version-5.3/indexes/querying/intersection.mdx index e0865784ab..36b4fea0d3 100644 --- a/versioned_docs/version-5.3/indexes/querying/intersection.mdx +++ b/versioned_docs/version-5.3/indexes/querying/intersection.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/morelikethis.mdx b/versioned_docs/version-5.3/indexes/querying/morelikethis.mdx index 329d008646..4afb9bc002 100644 --- a/versioned_docs/version-5.3/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-5.3/indexes/querying/morelikethis.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/paging.mdx b/versioned_docs/version-5.3/indexes/querying/paging.mdx index 0f8b5f2119..afb88f4e87 100644 --- a/versioned_docs/version-5.3/indexes/querying/paging.mdx +++ b/versioned_docs/version-5.3/indexes/querying/paging.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/projections.mdx b/versioned_docs/version-5.3/indexes/querying/projections.mdx index 19060c8668..55e7ce64bf 100644 --- a/versioned_docs/version-5.3/indexes/querying/projections.mdx +++ b/versioned_docs/version-5.3/indexes/querying/projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/query-index.mdx b/versioned_docs/version-5.3/indexes/querying/query-index.mdx index 265cf6ac4d..be7aad31ee 100644 --- a/versioned_docs/version-5.3/indexes/querying/query-index.mdx +++ b/versioned_docs/version-5.3/indexes/querying/query-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/searching.mdx b/versioned_docs/version-5.3/indexes/querying/searching.mdx index aa9612803b..f2c874aa54 100644 --- a/versioned_docs/version-5.3/indexes/querying/searching.mdx +++ b/versioned_docs/version-5.3/indexes/querying/searching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/sorting.mdx b/versioned_docs/version-5.3/indexes/querying/sorting.mdx index 813b9b7d90..7e2a212636 100644 --- a/versioned_docs/version-5.3/indexes/querying/sorting.mdx +++ b/versioned_docs/version-5.3/indexes/querying/sorting.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/spatial.mdx b/versioned_docs/version-5.3/indexes/querying/spatial.mdx index faa4bafa44..f21e0d149d 100644 --- a/versioned_docs/version-5.3/indexes/querying/spatial.mdx +++ b/versioned_docs/version-5.3/indexes/querying/spatial.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-5.3/indexes/querying/suggestions.mdx b/versioned_docs/version-5.3/indexes/querying/suggestions.mdx index 21373a5ec6..683ca785cd 100644 --- a/versioned_docs/version-5.3/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-5.3/indexes/querying/suggestions.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/sorting-and-collation.mdx b/versioned_docs/version-5.3/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-5.3/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-5.3/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-5.3/indexes/stale-indexes.mdx b/versioned_docs/version-5.3/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-5.3/indexes/stale-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/storing-data-in-index.mdx b/versioned_docs/version-5.3/indexes/storing-data-in-index.mdx index 69fcfe1448..04fecaae71 100644 --- a/versioned_docs/version-5.3/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-5.3/indexes/storing-data-in-index.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/using-analyzers.mdx b/versioned_docs/version-5.3/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-5.3/indexes/using-analyzers.mdx +++ b/versioned_docs/version-5.3/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/using-dynamic-fields.mdx b/versioned_docs/version-5.3/indexes/using-dynamic-fields.mdx index ee3eaf7804..570965a08c 100644 --- a/versioned_docs/version-5.3/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-5.3/indexes/using-dynamic-fields.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/using-term-vectors.mdx b/versioned_docs/version-5.3/indexes/using-term-vectors.mdx index b212047366..77306fede2 100644 --- a/versioned_docs/version-5.3/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-5.3/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/indexes/what-are-indexes.mdx b/versioned_docs/version-5.3/indexes/what-are-indexes.mdx index 57c6232bef..a50a4aad00 100644 --- a/versioned_docs/version-5.3/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-5.3/indexes/what-are-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/server/_embedded-csharp.mdx b/versioned_docs/version-5.3/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/server/_embedded-csharp.mdx rename to versioned_docs/version-5.3/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-5.3/server/_embedded-java.mdx b/versioned_docs/version-5.3/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-5.3/server/_embedded-java.mdx rename to versioned_docs/version-5.3/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-5.3/server/embedded.mdx b/versioned_docs/version-5.3/server/embedded.mdx index 0123e5edc1..d85eb8ae3e 100644 --- a/versioned_docs/version-5.3/server/embedded.mdx +++ b/versioned_docs/version-5.3/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-5.3/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-5.3/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-5.3/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-5.3/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-5.3/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.3/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-5.3/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-5.3/server/storage/documents-compression.mdx b/versioned_docs/version-5.3/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-5.3/server/storage/documents-compression.mdx +++ b/versioned_docs/version-5.3/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-5.3/start/_test-driver-csharp.mdx b/versioned_docs/version-5.3/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.3/start/_test-driver-csharp.mdx rename to versioned_docs/version-5.3/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-5.3/start/_test-driver-java.mdx b/versioned_docs/version-5.3/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-5.3/start/_test-driver-java.mdx rename to versioned_docs/version-5.3/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-5.3/start/test-driver.mdx b/versioned_docs/version-5.3/start/test-driver.mdx index caaf54ab4c..76d2299c77 100644 --- a/versioned_docs/version-5.3/start/test-driver.mdx +++ b/versioned_docs/version-5.3/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-5.4/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-5.4/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-5.4/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-5.4/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-5.4/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-5.4/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-5.4/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-5.4/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-5.4/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-5.4/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-5.4/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-5.4/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-5.4/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-5.4/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-5.4/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-5.4/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-5.4/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-5.4/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-5.4/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-5.4/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-5.4/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-5.4/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-5.4/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-5.4/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-5.4/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 3fbea43e2e..eaccf2717d 100644 --- a/versioned_docs/version-5.4/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-5.4/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_delete-nodejs.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_delete-nodejs.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_delete-php.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_delete-php.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_delete-php.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_delete-python.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_delete-python.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_delete-python.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_get-php.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_get-php.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_get-php.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_get-python.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_get-python.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_get-python.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_put-nodejs.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_put-nodejs.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_put-php.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_put-php.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_put-php.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/_put-python.mdx b/versioned_docs/version-5.4/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/_put-python.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/content/_put-python.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/delete.mdx b/versioned_docs/version-5.4/client-api/commands/documents/delete.mdx index 328b6cebe5..416b8950e2 100644 --- a/versioned_docs/version-5.4/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-5.4/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/commands/documents/get.mdx b/versioned_docs/version-5.4/client-api/commands/documents/get.mdx index d93b079fdd..1a25e897db 100644 --- a/versioned_docs/version-5.4/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-5.4/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx b/versioned_docs/version-5.4/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/how-to/_get-document-metadata-only-csharp.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/how-to/content/_get-document-metadata-only-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx b/versioned_docs/version-5.4/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/commands/documents/how-to/_get-document-metadata-only-java.mdx rename to versioned_docs/version-5.4/client-api/commands/documents/how-to/content/_get-document-metadata-only-java.mdx diff --git a/versioned_docs/version-5.4/client-api/commands/documents/how-to/get-document-metadata-only.mdx b/versioned_docs/version-5.4/client-api/commands/documents/how-to/get-document-metadata-only.mdx index 8aba404027..2b0483321a 100644 --- a/versioned_docs/version-5.4/client-api/commands/documents/how-to/get-document-metadata-only.mdx +++ b/versioned_docs/version-5.4/client-api/commands/documents/how-to/get-document-metadata-only.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDocumentMetadataOnlyCsharp from './_get-document-metadata-only-csharp.mdx'; -import GetDocumentMetadataOnlyJava from './_get-document-metadata-only-java.mdx'; +import GetDocumentMetadataOnlyCsharp from './content/_get-document-metadata-only-csharp.mdx'; +import GetDocumentMetadataOnlyJava from './content/_get-document-metadata-only-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/commands/documents/put.mdx b/versioned_docs/version-5.4/client-api/commands/documents/put.mdx index f2fd39fec9..c545cdab80 100644 --- a/versioned_docs/version-5.4/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-5.4/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_querying-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_querying-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_querying-java.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_querying-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_querying-java.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_querying-java.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-5.4/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-5.4/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/conventions.mdx b/versioned_docs/version-5.4/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/versioned_docs/version-5.4/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/deserialization.mdx b/versioned_docs/version-5.4/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-5.4/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-5.4/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-5.4/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to versioned_docs/version-5.4/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/versioned_docs/version-5.4/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-5.4/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/versioned_docs/version-5.4/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/querying.mdx b/versioned_docs/version-5.4/client-api/configuration/querying.mdx index eddc8e8e0e..b099c78cfd 100644 --- a/versioned_docs/version-5.4/client-api/configuration/querying.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingJava from './_querying-java.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingJava from './content/_querying-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/configuration/serialization.mdx b/versioned_docs/version-5.4/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-5.4/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-5.4/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-5.4/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-5.4/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/_creating-document-store-java.mdx b/versioned_docs/version-5.4/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-5.4/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-5.4/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-5.4/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-5.4/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-5.4/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-5.4/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-5.4/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-5.4/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-5.4/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-5.4/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-5.4/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/creating-document-store.mdx b/versioned_docs/version-5.4/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-5.4/client-api/creating-document-store.mdx +++ b/versioned_docs/version-5.4/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index f1060541f7..0000000000 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index b041e66af7..0000000000 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 3426efa1e3..0000000000 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,132 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -Data subscriptions provide a reliable and handy way to perform document processing on the client side. -The server sends batches of documents to the client. -The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. -The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/concurrent-subscriptions.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_examples-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..e4db04bee5 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..2be5da50f0 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..0a97729fc2 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,132 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +Data subscriptions provide a reliable and handy way to perform document processing on the client side. +The server sends batches of documents to the client. +The client then processes the batch and will receive the next one *only after it acknowledges* the batch was processed. +The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_examples-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to versioned_docs/version-5.4/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-5.4/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 6fa68306df..65475bc7b3 100644 --- a/versioned_docs/version-5.4/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-5.4/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-5.4/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-5.4/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-5.4/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-5.4/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-5.4/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-5.4/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-5.4/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-5.4/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-5.4/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-5.4/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-nodejs.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_use-low-level-commands-csharp.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_use-low-level-commands-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_use-low-level-commands-csharp.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_use-low-level-commands-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/_use-low-level-commands-java.mdx b/versioned_docs/version-5.4/client-api/how-to/content/_use-low-level-commands-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/how-to/_use-low-level-commands-java.mdx rename to versioned_docs/version-5.4/client-api/how-to/content/_use-low-level-commands-java.mdx diff --git a/versioned_docs/version-5.4/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-5.4/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/versioned_docs/version-5.4/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-5.4/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-5.4/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-5.4/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-5.4/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/how-to/use-low-level-commands.mdx b/versioned_docs/version-5.4/client-api/how-to/use-low-level-commands.mdx index 2cf745216e..9fd39af33a 100644 --- a/versioned_docs/version-5.4/client-api/how-to/use-low-level-commands.mdx +++ b/versioned_docs/version-5.4/client-api/how-to/use-low-level-commands.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UseLowLevelCommandsCsharp from './_use-low-level-commands-csharp.mdx'; -import UseLowLevelCommandsJava from './_use-low-level-commands-java.mdx'; +import UseLowLevelCommandsCsharp from './content/_use-low-level-commands-csharp.mdx'; +import UseLowLevelCommandsJava from './content/_use-low-level-commands-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/net-client-versions.mdx b/versioned_docs/version-5.4/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-5.4/client-api/net-client-versions.mdx +++ b/versioned_docs/version-5.4/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_delete-attachment-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_get-attachment-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_get-attachment-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/attachments/_put-attachment-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/attachments/content/_put-attachment-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/delete-attachment.mdx index b1b8dc0862..b4a5d42046 100644 --- a/versioned_docs/version-5.4/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-5.4/client-api/operations/attachments/delete-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; -import DeleteAttachmentNodejs from './_delete-attachment-nodejs.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; +import DeleteAttachmentNodejs from './content/_delete-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/get-attachment.mdx index dfbe7f67bf..16af9d26fc 100644 --- a/versioned_docs/version-5.4/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-5.4/client-api/operations/attachments/get-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; -import GetAttachmentNodejs from './_get-attachment-nodejs.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; +import GetAttachmentNodejs from './content/_get-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-5.4/client-api/operations/attachments/put-attachment.mdx index 7d63f1af0f..19a6aa8702 100644 --- a/versioned_docs/version-5.4/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-5.4/client-api/operations/attachments/put-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; -import PutAttachmentNodejs from './_put-attachment-nodejs.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; +import PutAttachmentNodejs from './content/_put-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-php.mdx b/versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-php.mdx rename to versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-python.mdx b/versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/common/_delete-by-query-python.mdx rename to versioned_docs/version-5.4/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-5.4/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/versioned_docs/version-5.4/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-5.4/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-php.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-php.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-python.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_overview-python.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_overview-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 5cd2b2f3bb..4dbcb13cc5 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; -import DeleteCompareExchangeValueNodejs from './_delete-compare-exchange-value-nodejs.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueNodejs from './content/_delete-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 5a3faf4c6d..797adb1e32 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; -import GetCompareExchangeValueNodejs from './_get-compare-exchange-value-nodejs.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueNodejs from './content/_get-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index 3cd524682d..7371593482 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; -import GetCompareExchangeValuesNodejs from './_get-compare-exchange-values-nodejs.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesNodejs from './content/_get-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/include-compare-exchange.mdx index ef602a655c..c2da54868f 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; -import IncludeCompareExchangeNodejs from './_include-compare-exchange-nodejs.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeNodejs from './content/_include-compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/overview.mdx index 66ee3a1273..d63e1a098c 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "php"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-5.4/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index ed5ae625f9..fe51a43af8 100644 --- a/versioned_docs/version-5.4/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-5.4/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; -import PutCompareExchangeValueNodejs from './_put-compare-exchange-value-nodejs.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueNodejs from './content/_put-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/_what-are-operations-php.mdx b/versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/_what-are-operations-php.mdx rename to versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/_what-are-operations-python.mdx b/versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/_what-are-operations-python.mdx rename to versioned_docs/version-5.4/client-api/operations/content/_what-are-operations-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-php.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_counter-batch-php.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_get-counters-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_get-counters-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/_get-counters-php.mdx b/versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/counters/_get-counters-php.mdx rename to versioned_docs/version-5.4/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-5.4/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/versioned_docs/version-5.4/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-5.4/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-5.4/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/versioned_docs/version-5.4/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-5.4/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to versioned_docs/version-5.4/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-5.4/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index dbbb74bb3e..81f30c05e4 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 8870c1da85..418075a390 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 715c28bc20..e48caa5360 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/_get-stats-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/add-etl.mdx index b849a0157c..83767b75af 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/get-identities.mdx index 0a5fdffa45..5bc99a1074 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-5.4/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_set-based-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_set-based-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/_single-document-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/patching/_single-document-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/patching/set-based.mdx b/versioned_docs/version-5.4/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/versioned_docs/version-5.4/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-5.4/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/patching/single-document.mdx b/versioned_docs/version-5.4/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/versioned_docs/version-5.4/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-5.4/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-php.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-php.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-python.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_add-database-node-python.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-php.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-php.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-python.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_compact-database-python.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/create-database.mdx index fb3313d4b2..01e457774f 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-5.4/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-5.4/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/operations/what-are-operations.mdx b/versioned_docs/version-5.4/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/versioned_docs/version-5.4/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-5.4/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-5.4/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-5.4/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/security/deserialization-security.mdx b/versioned_docs/version-5.4/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-5.4/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-5.4/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index 811678c09d..0000000000 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - session.Store(new User(), "users/johndoe"); - session.SaveChanges(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var session1 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var session2 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = session1.Load("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = session2.Load("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - session1.SaveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - session2.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - await asyncSession.SaveChangesAsync(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var asyncSession1 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var asyncSession2 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // asyncSession1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - await asyncSession1.SaveChangesAsync(); - - // asyncSession2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - await asyncSession2.SaveChangesAsync(); -} -`} - - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - session.Store(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`Load` the document into the session before storing it** - - even if the document is expected to be new. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating a new one or modifying if already exists - var user = session.Load("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - session.Store(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating or updating - var user = await asyncSession.LoadAsync("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - await asyncSession.StoreAsync(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index d9ae1ff263..0000000000 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,261 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session: -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two concurrent cluster-wide sessions: -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// Both sessions load the same document: -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 saves its changes first — -// this increments the Raft index of the associated atomic guard. -await session1.saveChanges(); - -// session2 tries to save using an outdated atomic guard version -// and fails with a ConcurrencyException. -await session2.saveChanges(); -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`const session = documentStore.openSession(\{ - // Open a cluster-wide session - transactionMode: "ClusterWide" -\}); - -// Load the user document BEFORE creating or updating -const user = await session.load("users/johndoe"); - -if (!user) \{ - // Document doesn't exist => create a new document - const newUser = \{ - name: "John Doe", - // ... initialize other properties - \}; - - // Store the new user document in the session - await session.store(newUser, "users/johndoe"); - -\} else \{ - // Document exists => apply your modifications - user.name = "New name"; - // ... make any other updates - - // No need to call store() again - // RavenDB tracks changes on loaded entities -\} - -// Commit your changes -await session.saveChanges(); -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-php.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-php.mdx deleted file mode 100644 index aee89e6ab0..0000000000 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-php.mdx +++ /dev/null @@ -1,276 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`// Open a cluster-wide session: -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // An atomic-guard is now automatically created for the new document "users/johndoe". - $session->saveChanges(); -\} finally \{ - $session->close(); -\} - -// Open two concurrent cluster-wide sessions: - -$sessionOptions1 = new SessionOptions(); -$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); - -$session1 = $store->openSession($sessionOptions1); -try \{ - $sessionOptions2 = new SessionOptions(); - $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); - $session2 = $store->openSession($sessionOptions2); - - try \{ - // Both sessions load the same document: - var $loadedUser1 = $session1->load(User::class, "users/johndoe"); - $loadedUser1->setName("jindoe"); - - $loadedUser2 = $session2->load(User::class, "users/johndoe"); - $loadedUser2->setName("jandoe"); - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - $session1->saveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - $session2->saveChanges(); - \} finally \{ - $session2->close(); - \} - -\} finally \{ - $session1->close(); -\} -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); -$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // No atomic-guard will be created upon saveChanges - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`// Open a cluster-wide session -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); -try \{ - // Load the user document BEFORE creating or updating - $user = $session->load(User::class, "users/johndoe"); - - if ($user === null) \{ - // Document doesn't exist => create a new document: - $newUser = new User(); - $newUser->setName("John Doe"); - // ... initialize other properties - - // Store the new user document in the session - $session->store($newUser, "users/johndoe"); - \} else \{ - // Document exists => apply your modifications: - $user->setName("New name"); - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - \} - - // Commit your changes - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-python.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-python.mdx deleted file mode 100644 index e650aac9bf..0000000000 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_atomic-guards-python.mdx +++ /dev/null @@ -1,251 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`with store.open_session( - # Open a cluster-wide session: - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session: - session.store(User(), "users/johndoe") - session.save_changes() - # An atomic-guard is now automatically created for the new document "users/johndoe" - -# Open two concurrent cluster-wide sessions: -with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session1: - with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) - ) as session2: - # Both sessions load the same document: - loaded_user_1 = session1.load("users/johndoe", User) - loaded_user_1.name = "jindoe" - loaded_user_2 = session2.load("users/johndoe", User) - loaded_user_2.name = "jandoe" - - # session1 saves its changes first — - # this increments the Raft index of the associated atomic guard. - session1.save_changes() - - # session2 tries to save using an outdated atomic guard version - # and fails with a ConcurrencyException. - session2.save_changes() -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`with store.open_session( - # Open a cluster-wide session - session_options=SessionOptions( - transaction_mode=TransactionMode.CLUSTER_WIDE, - disable_atomic_document_writes_in_cluster_wide_transaction=True, - ) -) as session: - session.store(User(), "users/johndoe") - - # No atomic-guard will be created upon save_changes - session.save_changes() -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`with store.open_session( - session_options=SessionOptions( - # Open a cluster-wide session - transaction_mode=TransactionMode.CLUSTER_WIDE - ) -) as session: - # Load the user document BEFORE creating or updating - user = session.load("users/johndoe", User) - - if user is None: - # Document doesn't exist => create a new document - new_user = User() - new_user.name = "John Doe" - # ... initialize other properties - - # Store the new user document in the session - session.store(new_user, "users/johndoe") - else: - # Document exists => apply your modifications - user.name = "New name" - # ... make any other updates - - # No need to call store() again - # RavenDB tracks changes on loaded entities - - # Commit your changes - session.save_changes() -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/atomic-guards.mdx index 8e705c3a32..29ace602dc 100644 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsPython from './_atomic-guards-python.mdx'; -import AtomicGuardsPhp from './_atomic-guards-php.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsPython from './content/_atomic-guards-python.mdx'; +import AtomicGuardsPhp from './content/_atomic-guards-php.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/compare-exchange.mdx index d4bdc9d5da..a98b9edf99 100644 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangePython from './_compare-exchange-python.mdx'; -import CompareExchangePhp from './_compare-exchange-php.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangePython from './content/_compare-exchange-python.mdx'; +import CompareExchangePhp from './content/_compare-exchange-php.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..9c603424ba --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + session.Store(new User(), "users/johndoe"); + session.SaveChanges(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var session1 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var session2 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = session1.Load("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = session2.Load("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + session1.SaveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + session2.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + await asyncSession.SaveChangesAsync(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var asyncSession1 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var asyncSession2 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // asyncSession1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + await asyncSession1.SaveChangesAsync(); + + // asyncSession2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + await asyncSession2.SaveChangesAsync(); +} +`} + + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + session.Store(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`Load` the document into the session before storing it** - + even if the document is expected to be new. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating a new one or modifying if already exists + var user = session.Load("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + session.Store(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating or updating + var user = await asyncSession.LoadAsync("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + await asyncSession.StoreAsync(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..2825373609 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,261 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session: +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two concurrent cluster-wide sessions: +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// Both sessions load the same document: +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 saves its changes first — +// this increments the Raft index of the associated atomic guard. +await session1.saveChanges(); + +// session2 tries to save using an outdated atomic guard version +// and fails with a ConcurrencyException. +await session2.saveChanges(); +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`const session = documentStore.openSession(\{ + // Open a cluster-wide session + transactionMode: "ClusterWide" +\}); + +// Load the user document BEFORE creating or updating +const user = await session.load("users/johndoe"); + +if (!user) \{ + // Document doesn't exist => create a new document + const newUser = \{ + name: "John Doe", + // ... initialize other properties + \}; + + // Store the new user document in the session + await session.store(newUser, "users/johndoe"); + +\} else \{ + // Document exists => apply your modifications + user.name = "New name"; + // ... make any other updates + + // No need to call store() again + // RavenDB tracks changes on loaded entities +\} + +// Commit your changes +await session.saveChanges(); +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx new file mode 100644 index 0000000000..c6fcf1e501 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx @@ -0,0 +1,276 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`// Open a cluster-wide session: +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // An atomic-guard is now automatically created for the new document "users/johndoe". + $session->saveChanges(); +\} finally \{ + $session->close(); +\} + +// Open two concurrent cluster-wide sessions: + +$sessionOptions1 = new SessionOptions(); +$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); + +$session1 = $store->openSession($sessionOptions1); +try \{ + $sessionOptions2 = new SessionOptions(); + $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); + $session2 = $store->openSession($sessionOptions2); + + try \{ + // Both sessions load the same document: + var $loadedUser1 = $session1->load(User::class, "users/johndoe"); + $loadedUser1->setName("jindoe"); + + $loadedUser2 = $session2->load(User::class, "users/johndoe"); + $loadedUser2->setName("jandoe"); + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + $session1->saveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + $session2->saveChanges(); + \} finally \{ + $session2->close(); + \} + +\} finally \{ + $session1->close(); +\} +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); +$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // No atomic-guard will be created upon saveChanges + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`// Open a cluster-wide session +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); +try \{ + // Load the user document BEFORE creating or updating + $user = $session->load(User::class, "users/johndoe"); + + if ($user === null) \{ + // Document doesn't exist => create a new document: + $newUser = new User(); + $newUser->setName("John Doe"); + // ... initialize other properties + + // Store the new user document in the session + $session->store($newUser, "users/johndoe"); + \} else \{ + // Document exists => apply your modifications: + $user->setName("New name"); + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + \} + + // Commit your changes + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx new file mode 100644 index 0000000000..489119ff63 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx @@ -0,0 +1,251 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`with store.open_session( + # Open a cluster-wide session: + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session: + session.store(User(), "users/johndoe") + session.save_changes() + # An atomic-guard is now automatically created for the new document "users/johndoe" + +# Open two concurrent cluster-wide sessions: +with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session1: + with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) + ) as session2: + # Both sessions load the same document: + loaded_user_1 = session1.load("users/johndoe", User) + loaded_user_1.name = "jindoe" + loaded_user_2 = session2.load("users/johndoe", User) + loaded_user_2.name = "jandoe" + + # session1 saves its changes first — + # this increments the Raft index of the associated atomic guard. + session1.save_changes() + + # session2 tries to save using an outdated atomic guard version + # and fails with a ConcurrencyException. + session2.save_changes() +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`with store.open_session( + # Open a cluster-wide session + session_options=SessionOptions( + transaction_mode=TransactionMode.CLUSTER_WIDE, + disable_atomic_document_writes_in_cluster_wide_transaction=True, + ) +) as session: + session.store(User(), "users/johndoe") + + # No atomic-guard will be created upon save_changes + session.save_changes() +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`with store.open_session( + session_options=SessionOptions( + # Open a cluster-wide session + transaction_mode=TransactionMode.CLUSTER_WIDE + ) +) as session: + # Load the user document BEFORE creating or updating + user = session.load("users/johndoe", User) + + if user is None: + # Document doesn't exist => create a new document + new_user = User() + new_user.name = "John Doe" + # ... initialize other properties + + # Store the new user document in the session + session.store(new_user, "users/johndoe") + else: + # Document exists => apply your modifications + user.name = "New name" + # ... make any other updates + + # No need to call store() again + # RavenDB tracks changes on loaded entities + + # Commit your changes + session.save_changes() +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-php.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-php.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-python.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_compare-exchange-python.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-php.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-php.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-python.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/cluster-transaction/_overview-python.mdx rename to versioned_docs/version-5.4/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-5.4/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/versioned_docs/version-5.4/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-5.4/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to versioned_docs/version-5.4/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-5.4/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/versioned_docs/version-5.4/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-5.4/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_deleting-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_deleting-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_deleting-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_deleting-entities-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_deleting-entities-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_deleting-entities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_loading-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_loading-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_loading-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_loading-entities-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_loading-entities-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_loading-entities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_opening-a-session-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_opening-a-session-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_opening-a-session-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_opening-a-session-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_opening-a-session-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_opening-a-session-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_saving-changes-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_saving-changes-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_saving-changes-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_saving-changes-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_saving-changes-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_saving-changes-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_storing-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_storing-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_storing-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_storing-entities-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_storing-entities-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_storing-entities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_updating-entities-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_updating-entities-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_updating-entities-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_updating-entities-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_updating-entities-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_updating-entities-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to versioned_docs/version-5.4/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/deleting-entities.mdx b/versioned_docs/version-5.4/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/versioned_docs/version-5.4/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-5.4/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-5.4/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-5.4/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-5.4/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-5.4/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-document-exists-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_clear-a-session-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_defer-operations-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-current-session-node-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-counters-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-php.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-php.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-python.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_refresh-entity-python.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-5.4/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-5.4/client-api/session/how-to/evict-entity-from-a-session.mdx index 958fc3efc6..b8527408ff 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/get-tracked-entities.mdx b/versioned_docs/version-5.4/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/get-tracked-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-5.4/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-5.4/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-5.4/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-5.4/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-5.4/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-5.4/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/loading-entities.mdx b/versioned_docs/version-5.4/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/versioned_docs/version-5.4/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/opening-a-session.mdx b/versioned_docs/version-5.4/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/versioned_docs/version-5.4/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-5.4/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 354557c2b6..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,955 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index 3312ef781c..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,504 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - **Circle**: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - **Polygon**: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - **Polygon rules**: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. - - - - **Order by distance**: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - **Order by distance descending**: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - **Sort results by rounded distance**: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - **Get resulting distance**: - -* The distance is available in the `@spatial` metadata property within each result. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index). | -| **field** | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| **clause** | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| **latitude** | `string` | Path to the document field that contains the latitude | -| **longitude** | `string` | Path to the document field that contains the longitude | -| **wktPath** | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `number` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Path to spatial field in index
(when querying an index). | -| **field** | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `number` | Used to define a point from which distance will be measured | -| **roundFactor** | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index 467c5d4367..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,532 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) # todo gracjan: check if its possible to order by again without then_by - # todo reeb: skip this example for now, we'll get back to it later on - # A secondary sort can be applied -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -The distance is available in the `@spatial` metadata property within each result. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 2767086d97..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index ca6f981b62..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,465 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -|--------------|-----------------------|-------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode ` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-count-query-results-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-customize-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..e457478c36 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,955 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..57d485fed0 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,504 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + **Circle**: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + **Polygon**: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + **Polygon rules**: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. + + + + **Order by distance**: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + **Order by distance descending**: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + **Sort results by rounded distance**: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + **Get resulting distance**: + +* The distance is available in the `@spatial` metadata property within each result. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index). | +| **field** | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| **clause** | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| **latitude** | `string` | Path to the document field that contains the latitude | +| **longitude** | `string` | Path to the document field that contains the longitude | +| **wktPath** | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `number` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Path to spatial field in index
(when querying an index). | +| **field** | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `number` | Used to define a point from which distance will be measured | +| **roundFactor** | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..3ba227e79f --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,532 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) # todo gracjan: check if its possible to order by again without then_by + # todo reeb: skip this example for now, we'll get back to it later on + # A secondary sort can be applied +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +The distance is available in the `@spatial` metadata property within each result. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-project-query-results-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-intersect-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..1d4b9221d7 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f912ddf78b --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,465 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +|--------------|-----------------------|-------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode ` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/_sort-query-results-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index ced793543f..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 5865ccae9b..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| ****timings** | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **DurationInMs** | `long` | Total duration | -| **Timings** | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index b4c6b9da8a..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,47 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -## Example - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from Products -where search(Name, 'Syrup') -include timings() -`} - - - - ---- - -When you run the query with `include timings()` in Studio, extra tab appears. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 9a57a25391..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,97 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **timingsCallback** | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| **durationInMs** | `number` | Total duration | -| **timings** | `Record` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 83af72a821..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,79 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index 85298a4b93..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,109 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..54a96307a9 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..0c81ca407f --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| ****timings** | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **DurationInMs** | `long` | Total duration | +| **Timings** | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..2181b57837 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,47 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces. + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +## Example + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from Products +where search(Name, 'Syrup') +include timings() +`} + + + + +--- + +When you run the query with `include timings()` in Studio, extra tab appears. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..91b0956a7c --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,97 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **timingsCallback** | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| **durationInMs** | `number` | Total duration | +| **timings** | `Record` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..1db9947aa7 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,79 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..891b40611b --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,109 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-5.4/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-project-query-results.mdx index 89f89d0822..187a394822 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-5.4/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/sort-query-results.mdx index a34e918743..26b8cb85a3 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/sort-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 4d6da16a2d..0000000000 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,373 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) - -# todo reeb & gracjan: lets implement it after 5.4 release -# i have a perfect ticket for that -# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_full-text-search-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..0bf2fc548a --- /dev/null +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,373 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) + +# todo reeb & gracjan: lets implement it after 5.4 release +# i have a perfect ticket for that +# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_proximity-search-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-php.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-php.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-python.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/session/querying/text-search/_using-regex-python.mdx rename to versioned_docs/version-5.4/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-5.4/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/versioned_docs/version-5.4/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-5.4/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/saving-changes.mdx b/versioned_docs/version-5.4/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/versioned_docs/version-5.4/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-5.4/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/storing-entities.mdx b/versioned_docs/version-5.4/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/versioned_docs/version-5.4/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/updating-entities.mdx b/versioned_docs/version-5.4/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/versioned_docs/version-5.4/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-5.4/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-5.4/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/versioned_docs/version-5.4/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-5.4/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-5.4/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-5.4/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-5.4/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/setting-up-default-database.mdx b/versioned_docs/version-5.4/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-5.4/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-5.4/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-5.4/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-5.4/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-5.4/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-5.4/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-5.4/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/client-api/what-is-a-document-store.mdx b/versioned_docs/version-5.4/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-5.4/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-5.4/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/bulk-insert.mdx b/versioned_docs/version-5.4/document-extensions/attachments/bulk-insert.mdx index c763b6a3ca..296538d2fa 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/bulk-insert.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/bulk-insert.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BulkInsertCsharp from './_bulk-insert-csharp.mdx'; -import BulkInsertPython from './_bulk-insert-python.mdx'; -import BulkInsertNodejs from './_bulk-insert-nodejs.mdx'; +import BulkInsertCsharp from './content/_bulk-insert-csharp.mdx'; +import BulkInsertPython from './content/_bulk-insert-python.mdx'; +import BulkInsertNodejs from './content/_bulk-insert-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_bulk-insert-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_bulk-insert-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-php.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-php.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_copying-moving-renaming-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_copying-moving-renaming-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_deleting-php.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_deleting-php.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_deleting-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_deleting-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_deleting-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_indexing-php.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_indexing-php.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_indexing-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_indexing-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_indexing-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_loading-php.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_loading-php.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_loading-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_loading-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_loading-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_loading-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_storing-php.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_storing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_storing-php.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_storing-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_storing-python.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_storing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_storing-python.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_storing-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-5.4/document-extensions/attachments/copying-moving-renaming.mdx index 5d9756c7ff..dd66ad7797 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; -import CopyingMovingRenamingPython from './_copying-moving-renaming-python.mdx'; -import CopyingMovingRenamingPhp from './_copying-moving-renaming-php.mdx'; -import CopyingMovingRenamingNodejs from './_copying-moving-renaming-nodejs.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingPython from './content/_copying-moving-renaming-python.mdx'; +import CopyingMovingRenamingPhp from './content/_copying-moving-renaming-php.mdx'; +import CopyingMovingRenamingNodejs from './content/_copying-moving-renaming-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/deleting.mdx b/versioned_docs/version-5.4/document-extensions/attachments/deleting.mdx index 412aa66a67..604c4058e7 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/deleting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingPython from './_deleting-python.mdx'; -import DeletingPhp from './_deleting-php.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingPython from './content/_deleting-python.mdx'; +import DeletingPhp from './content/_deleting-php.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/indexing.mdx b/versioned_docs/version-5.4/document-extensions/attachments/indexing.mdx index d49e97610c..8fca84b22e 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/loading.mdx b/versioned_docs/version-5.4/document-extensions/attachments/loading.mdx index b845db6865..6c82d701c2 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/storing.mdx b/versioned_docs/version-5.4/document-extensions/attachments/storing.mdx index 5e877c3b82..cb3e3b93d1 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/storing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringPython from './_storing-python.mdx'; -import StoringPhp from './_storing-php.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringPython from './content/_storing-python.mdx'; +import StoringPhp from './content/_storing-php.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-5.4/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-5.4/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-5.4/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_counters-and-other-features-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_create-or-modify-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_delete-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_delete-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_delete-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_delete-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_delete-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_delete-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_delete-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_delete-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_including-counters-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_including-counters-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_including-counters-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_including-counters-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_including-counters-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_including-counters-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_including-counters-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_including-counters-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_including-counters-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_including-counters-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_including-counters-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_indexing-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_indexing-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_indexing-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_indexing-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_indexing-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_indexing-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_overview-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_overview-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_overview-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_overview-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_overview-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_overview-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_overview-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-php.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-php.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-python.mdx b/versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/counters/_retrieve-counter-values-python.mdx rename to versioned_docs/version-5.4/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-5.4/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-5.4/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/delete.mdx b/versioned_docs/version-5.4/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/including-counters.mdx b/versioned_docs/version-5.4/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/including-counters.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/indexing.mdx b/versioned_docs/version-5.4/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/overview.mdx b/versioned_docs/version-5.4/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-5.4/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/versioned_docs/version-5.4/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-5.4/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 4365c1079c..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,321 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index 8b480d9db1..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,318 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_overview-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 0dd4ed178c..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,281 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 610bebb32b..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index 3c8783a8ad..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index d42399f08e..0000000000 --- a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/_overview-python.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_counting-python.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_including-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-php.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/client-api/session/_loading-python.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..0f66fc334b --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,321 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..b57988e8d8 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,318 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..63987fad60 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,281 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..2e366627d8 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6bf087d689 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..ab3a281b0b --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-5.4/document-extensions/revisions/overview.mdx b/versioned_docs/version-5.4/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/overview.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-5.4/document-extensions/revisions/revisions-and-other-features.mdx index dd80b671dc..38db72b2c8 100644 --- a/versioned_docs/version-5.4/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-5.4/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 509e667890..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,301 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series. -`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 782549d0c2..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,258 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series. -`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index eaeda8b14c..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,335 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------|------|-------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. -`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index 64b9871a61..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,310 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------|------|-------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. -`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/javascript-support.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/named-time-series-values.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/get.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/get.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/patch.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/overview.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/overview.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/append.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/append.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_append-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/delete.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/delete.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-names.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/overview.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/patch.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/patch.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/querying.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/querying.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_design-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_design-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_design-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_design-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_indexing-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_indexing-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_indexing-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_indexing-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_indexing-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_indexing-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/_indexing-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/_indexing-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..42b2a7615a --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,301 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series. +`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..fdd555002e --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,258 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series. +`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..88a235e310 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,335 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------|------|-------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. +`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..a88dec2de0 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,310 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------|------|-------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. +`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/design.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/design.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/indexing.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/indexing.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 2e1013e32c..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,318 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index ac0ea992b5..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,338 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index 83305e53a8..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,287 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index f5f7118bfa..0000000000 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,285 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/choosing-query-range.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_filtering-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..2f6b2c7fae --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,318 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..5f7217380a --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,338 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..50a24159be --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,287 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..6664e2ef48 --- /dev/null +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,285 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-php.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-python.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to versioned_docs/version-5.4/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/filtering.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/filtering.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/overview-and-syntax.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/querying/using-indexes.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/querying/using-indexes.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/rollup-and-retention.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/rollup-and-retention.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/document-extensions/timeseries/time-series-and-other-features.mdx b/versioned_docs/version-5.4/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/versioned_docs/version-5.4/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/versioned_docs/version-5.4/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-5.4/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-5.4/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-5.4/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_index-query-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_index-query-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_query-result-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_query-result-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/_stream-result-csharp.mdx b/versioned_docs/version-5.4/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-5.4/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-5.4/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-5.4/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-5.4/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/counters-batch-command-data.mdx b/versioned_docs/version-5.4/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-5.4/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/delete-command-data.mdx b/versioned_docs/version-5.4/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-5.4/glossary/delete-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-5.4/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-5.4/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/index-query.mdx b/versioned_docs/version-5.4/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-5.4/glossary/index-query.mdx +++ b/versioned_docs/version-5.4/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/move-attachment-command-data.mdx b/versioned_docs/version-5.4/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-5.4/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/patch-command-data.mdx b/versioned_docs/version-5.4/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-5.4/glossary/patch-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/put-command-data.mdx b/versioned_docs/version-5.4/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-5.4/glossary/put-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-5.4/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-5.4/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-5.4/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/query-result.mdx b/versioned_docs/version-5.4/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-5.4/glossary/query-result.mdx +++ b/versioned_docs/version-5.4/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/stream-query-statistics.mdx b/versioned_docs/version-5.4/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-5.4/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-5.4/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-5.4/glossary/stream-result.mdx b/versioned_docs/version-5.4/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-5.4/glossary/stream-result.mdx +++ b/versioned_docs/version-5.4/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.4/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-5.4/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-nested-data-php.mdx b/versioned_docs/version-5.4/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-nested-data-python.mdx b/versioned_docs/version-5.4/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.4/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.4/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-related-documents-php.mdx b/versioned_docs/version-5.4/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.4/indexes/_indexing-related-documents-python.mdx b/versioned_docs/version-5.4/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/versioned_docs/version-5.4/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.4/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index af290517e0..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.4/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 035114b307..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,488 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.4/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 1cdf1853fa..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-php.mdx b/versioned_docs/version-5.4/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index f02a86fa8a..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,568 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | | | -|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`False` - will set `FieldStorage.NO` (default value) -`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`None` - `FieldIndexing.Default` (default value) -`False` - `FieldIndexing.Exact` -`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-python.mdx b/versioned_docs/version-5.4/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index 0490bf84df..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,520 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`False` - will set `FieldStorage.NO` (default value) -`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`None` - `FieldIndexing.Default` (default value) -`False` - `FieldIndexing.Exact` -`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-5.4/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.4/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/versioned_docs/version-5.4/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/versioned_docs/version-5.4/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index 131b68023e..0000000000 --- a/versioned_docs/version-5.4/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-5.4/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-5.4/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index 9086456c38..0000000000 --- a/versioned_docs/version-5.4/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-5.4/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/versioned_docs/version-5.4/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-5.4/indexes/_what-are-indexes-php.mdx b/versioned_docs/version-5.4/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/versioned_docs/version-5.4/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-5.4/indexes/_what-are-indexes-python.mdx b/versioned_docs/version-5.4/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/versioned_docs/version-5.4/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-5.4/indexes/boosting.mdx b/versioned_docs/version-5.4/indexes/boosting.mdx index 1a4f9e8126..e7a5bb4fd1 100644 --- a/versioned_docs/version-5.4/indexes/boosting.mdx +++ b/versioned_docs/version-5.4/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/_boosting-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_boosting-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_boosting-java.mdx b/versioned_docs/version-5.4/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_boosting-java.mdx rename to versioned_docs/version-5.4/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_boosting-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_boosting-php.mdx b/versioned_docs/version-5.4/indexes/content/_boosting-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_boosting-php.mdx rename to versioned_docs/version-5.4/indexes/content/_boosting-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-java.mdx b/versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-java.mdx rename to versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-php.mdx b/versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-php.mdx rename to versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-python.mdx b/versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_converting-to-json-and-accessing-metadata-python.mdx rename to versioned_docs/version-5.4/indexes/content/_converting-to-json-and-accessing-metadata-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-5.4/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-5.4/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_extending-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-5.4/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-basics-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-php.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-python.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.4/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-php.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-python.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-5.4/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-spatial-data-php.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-spatial-data-php.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_indexing-spatial-data-python.mdx b/versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_indexing-spatial-data-python.mdx rename to versioned_docs/version-5.4/indexes/content/_indexing-spatial-data-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-indexes-java.mdx rename to versioned_docs/version-5.4/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-indexes-php.mdx b/versioned_docs/version-5.4/indexes/content/_map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-indexes-php.mdx rename to versioned_docs/version-5.4/indexes/content/_map-indexes-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-indexes-python.mdx b/versioned_docs/version-5.4/indexes/content/_map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-indexes-python.mdx rename to versioned_docs/version-5.4/indexes/content/_map-indexes-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-reduce-indexes-php.mdx b/versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-reduce-indexes-php.mdx rename to versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_map-reduce-indexes-python.mdx b/versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_map-reduce-indexes-python.mdx rename to versioned_docs/version-5.4/indexes/content/_map-reduce-indexes-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-5.4/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_multi-map-indexes-php.mdx b/versioned_docs/version-5.4/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_multi-map-indexes-php.mdx rename to versioned_docs/version-5.4/indexes/content/_multi-map-indexes-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_multi-map-indexes-python.mdx b/versioned_docs/version-5.4/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_multi-map-indexes-python.mdx rename to versioned_docs/version-5.4/indexes/content/_multi-map-indexes-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-5.4/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-5.4/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_stale-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-5.4/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-5.4/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-5.4/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/_storing-data-in-index-php.mdx b/versioned_docs/version-5.4/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_storing-data-in-index-php.mdx rename to versioned_docs/version-5.4/indexes/content/_storing-data-in-index-php.mdx diff --git a/versioned_docs/version-5.4/indexes/_storing-data-in-index-python.mdx b/versioned_docs/version-5.4/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_storing-data-in-index-python.mdx rename to versioned_docs/version-5.4/indexes/content/_storing-data-in-index-python.mdx diff --git a/versioned_docs/version-5.4/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_using-analyzers-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_using-analyzers-csharp.mdx rename to versioned_docs/version-5.4/indexes/content/_using-analyzers-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/_using-analyzers-java.mdx b/versioned_docs/version-5.4/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-5.4/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_using-analyzers-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_using-analyzers-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_using-analyzers-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..46cd88508f --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..b575a1a3c0 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,488 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..27331b68cb --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-php.mdx b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..c5eafe9c00 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,568 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | | | +|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`False` - will set `FieldStorage.NO` (default value) +`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`None` - `FieldIndexing.Default` (default value) +`False` - `FieldIndexing.Exact` +`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-python.mdx b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..79953eb237 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,520 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`False` - will set `FieldStorage.NO` (default value) +`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`None` - `FieldIndexing.Default` (default value) +`False` - `FieldIndexing.Exact` +`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_using-term-vectors-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/versioned_docs/version-5.4/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-5.4/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-5.4/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-5.4/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-5.4/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/content/_what-are-indexes-csharp.mdx b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..94f39cce69 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_what-are-indexes-java.mdx b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..793f4a3e13 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_what-are-indexes-nodejs.mdx b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_what-are-indexes-php.mdx b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-5.4/indexes/content/_what-are-indexes-python.mdx b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/versioned_docs/version-5.4/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-5.4/indexes/converting-to-json-and-accessing-metadata.mdx b/versioned_docs/version-5.4/indexes/converting-to-json-and-accessing-metadata.mdx index 987a87f05b..ace912ae23 100644 --- a/versioned_docs/version-5.4/indexes/converting-to-json-and-accessing-metadata.mdx +++ b/versioned_docs/version-5.4/indexes/converting-to-json-and-accessing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConvertingToJsonAndAccessingMetadataCsharp from './_converting-to-json-and-accessing-metadata-csharp.mdx'; -import ConvertingToJsonAndAccessingMetadataJava from './_converting-to-json-and-accessing-metadata-java.mdx'; -import ConvertingToJsonAndAccessingMetadataPython from './_converting-to-json-and-accessing-metadata-python.mdx'; -import ConvertingToJsonAndAccessingMetadataPhp from './_converting-to-json-and-accessing-metadata-php.mdx'; -import ConvertingToJsonAndAccessingMetadataNodejs from './_converting-to-json-and-accessing-metadata-nodejs.mdx'; +import ConvertingToJsonAndAccessingMetadataCsharp from './content/_converting-to-json-and-accessing-metadata-csharp.mdx'; +import ConvertingToJsonAndAccessingMetadataJava from './content/_converting-to-json-and-accessing-metadata-java.mdx'; +import ConvertingToJsonAndAccessingMetadataPython from './content/_converting-to-json-and-accessing-metadata-python.mdx'; +import ConvertingToJsonAndAccessingMetadataPhp from './content/_converting-to-json-and-accessing-metadata-php.mdx'; +import ConvertingToJsonAndAccessingMetadataNodejs from './content/_converting-to-json-and-accessing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/creating-and-deploying.mdx b/versioned_docs/version-5.4/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/versioned_docs/version-5.4/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-5.4/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/extending-indexes.mdx b/versioned_docs/version-5.4/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-5.4/indexes/extending-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-basics.mdx b/versioned_docs/version-5.4/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-5.4/indexes/indexing-basics.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-5.4/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-5.4/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-5.4/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/versioned_docs/version-5.4/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-5.4/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-5.4/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-nested-data.mdx b/versioned_docs/version-5.4/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/versioned_docs/version-5.4/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-5.4/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/versioned_docs/version-5.4/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-related-documents.mdx b/versioned_docs/version-5.4/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/versioned_docs/version-5.4/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/indexing-spatial-data.mdx b/versioned_docs/version-5.4/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/versioned_docs/version-5.4/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-5.4/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/javascript-indexes.mdx b/versioned_docs/version-5.4/indexes/javascript-indexes.mdx index d120b3bc12..70bed49b28 100644 --- a/versioned_docs/version-5.4/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/javascript-indexes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; diff --git a/versioned_docs/version-5.4/indexes/map-indexes.mdx b/versioned_docs/version-5.4/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/versioned_docs/version-5.4/indexes/map-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/map-reduce-indexes.mdx b/versioned_docs/version-5.4/indexes/map-reduce-indexes.mdx index 0f4523b7fb..51f425d5d7 100644 --- a/versioned_docs/version-5.4/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/multi-map-indexes.mdx b/versioned_docs/version-5.4/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/versioned_docs/version-5.4/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/number-type-conversion.mdx b/versioned_docs/version-5.4/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-5.4/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-5.4/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 68108f6054..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1054 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } - public FacetOptions Options { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-5.4/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-5.4/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_faceted-search-php.mdx b/versioned_docs/version-5.4/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_faceted-search-python.mdx b/versioned_docs/version-5.4/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 3bdadb3fbb..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,780 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* **Paging policy**: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -int totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - - * Optimizes bandwidth usage by reducing data transfer between the server and client. - * Prevents delays in response times caused by sending too much data over the network. - * Avoids high memory consumption when dealing with numerous documents. - * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -int totalResults = 0; -int totalUniqueResults = 0; -int skippedResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_paging-java.mdx b/versioned_docs/version-5.4/indexes/querying/_paging-java.mdx deleted file mode 100644 index 967347d062..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,303 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* **Paging policy**: - To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, - which can be useful during development or testing phases. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 862c50d59b..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* **Paging policy**: - To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, - which can be useful during development or testing phases. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_paging-php.mdx b/versioned_docs/version-5.4/indexes/querying/_paging-php.mdx deleted file mode 100644 index fb531d798b..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,685 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* **Paging policy**: - To prevent executing queries that do not specify a page size, you can set the - [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) - convention, which can be useful during development or testing phases. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - - * Optimizes bandwidth usage by reducing data transfer between the server and client. - * Prevents delays in response times caused by sending too much data over the network. - * Avoids high memory consumption when dealing with numerous documents. - * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_paging-python.mdx b/versioned_docs/version-5.4/indexes/querying/_paging-python.mdx deleted file mode 100644 index a0d0f9812e..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,428 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* **Paging policy**: - To prevent executing queries that do not specify a page size, you can set the - [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) - convention, which can be useful during development or testing phases. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - - * Optimizes bandwidth usage by reducing data transfer between the server and client. - * Prevents delays in response times caused by sending too much data over the network. - * Avoids high memory consumption when dealing with numerous documents. - * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_spatial-java.mdx b/versioned_docs/version-5.4/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_suggestions-php.mdx b/versioned_docs/version-5.4/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_suggestions-python.mdx b/versioned_docs/version-5.4/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/versioned_docs/version-5.4/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/versioned_docs/version-5.4/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_distinct-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_exploration-queries-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_exploration-queries-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_exploration-queries-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_exploration-queries-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_exploration-queries-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_exploration-queries-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_exploration-queries-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..4e63feda4d --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1054 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } + public FacetOptions Options { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_filtering-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_filtering-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_filtering-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_filtering-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_filtering-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_highlighting-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_highlighting-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_highlighting-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_highlighting-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_highlighting-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_highlighting-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_include-explanations-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_include-explanations-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_include-explanations-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_include-explanations-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_intersection-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_intersection-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_intersection-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_intersection-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_intersection-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_intersection-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_intersection-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_morelikethis-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_morelikethis-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_morelikethis-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_morelikethis-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_morelikethis-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_morelikethis-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..edcb76d883 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,780 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* **Paging policy**: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +int totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + + * Optimizes bandwidth usage by reducing data transfer between the server and client. + * Prevents delays in response times caused by sending too much data over the network. + * Avoids high memory consumption when dealing with numerous documents. + * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +int totalResults = 0; +int totalUniqueResults = 0; +int skippedResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..3ad1956b27 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,303 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* **Paging policy**: + To prevent executing queries that do not specify a page size, you can set the [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) convention, + which can be useful during development or testing phases. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..9f92e5be3b --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* **Paging policy**: + To prevent executing queries that do not specify a page size, you can set the `throwIfQueryPageSizeIsNotSet` convention, + which can be useful during development or testing phases. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_paging-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..5e40fe9bcc --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,685 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* **Paging policy**: + To prevent executing queries that do not specify a page size, you can set the + [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) + convention, which can be useful during development or testing phases. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + + * Optimizes bandwidth usage by reducing data transfer between the server and client. + * Prevents delays in response times caused by sending too much data over the network. + * Avoids high memory consumption when dealing with numerous documents. + * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_paging-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..ed38c5bd74 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,428 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* **Paging policy**: + To prevent executing queries that do not specify a page size, you can set the + [ThrowIfQueryPageSizeIsNotSet](../../client-api/configuration/querying.mdx#throwifquerypagesizeisnotset) + convention, which can be useful during development or testing phases. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + + * Optimizes bandwidth usage by reducing data transfer between the server and client. + * Prevents delays in response times caused by sending too much data over the network. + * Avoids high memory consumption when dealing with numerous documents. + * Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_projections-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_projections-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_projections-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_projections-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_projections-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_projections-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_projections-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_projections-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_projections-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_projections-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_query-index-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_query-index-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_query-index-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_query-index-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_query-index-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_query-index-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_query-index-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_searching-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_searching-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_searching-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_searching-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_searching-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_searching-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_searching-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_searching-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_sorting-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_sorting-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_sorting-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_sorting-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_sorting-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_sorting-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_sorting-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-5.4/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_spatial-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_spatial-php.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_spatial-php.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/_spatial-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_spatial-python.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_spatial-python.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-5.4/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-5.4/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-5.4/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_suggestions-php.mdx b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/content/_suggestions-python.mdx b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/versioned_docs/version-5.4/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/versioned_docs/version-5.4/indexes/querying/distinct.mdx b/versioned_docs/version-5.4/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-5.4/indexes/querying/distinct.mdx +++ b/versioned_docs/version-5.4/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/exploration-queries.mdx b/versioned_docs/version-5.4/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/versioned_docs/version-5.4/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-5.4/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/faceted-search.mdx b/versioned_docs/version-5.4/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/versioned_docs/version-5.4/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-5.4/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/filtering.mdx b/versioned_docs/version-5.4/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/versioned_docs/version-5.4/indexes/querying/filtering.mdx +++ b/versioned_docs/version-5.4/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/highlighting.mdx b/versioned_docs/version-5.4/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/versioned_docs/version-5.4/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-5.4/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/include-explanations.mdx b/versioned_docs/version-5.4/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/versioned_docs/version-5.4/indexes/querying/include-explanations.mdx +++ b/versioned_docs/version-5.4/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/intersection.mdx b/versioned_docs/version-5.4/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/versioned_docs/version-5.4/indexes/querying/intersection.mdx +++ b/versioned_docs/version-5.4/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/morelikethis.mdx b/versioned_docs/version-5.4/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/versioned_docs/version-5.4/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-5.4/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/paging.mdx b/versioned_docs/version-5.4/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/versioned_docs/version-5.4/indexes/querying/paging.mdx +++ b/versioned_docs/version-5.4/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/projections.mdx b/versioned_docs/version-5.4/indexes/querying/projections.mdx index dd5e2c5fcb..a0fa386545 100644 --- a/versioned_docs/version-5.4/indexes/querying/projections.mdx +++ b/versioned_docs/version-5.4/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/query-index.mdx b/versioned_docs/version-5.4/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/versioned_docs/version-5.4/indexes/querying/query-index.mdx +++ b/versioned_docs/version-5.4/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/searching.mdx b/versioned_docs/version-5.4/indexes/querying/searching.mdx index 9505b02c2d..dce09c5fab 100644 --- a/versioned_docs/version-5.4/indexes/querying/searching.mdx +++ b/versioned_docs/version-5.4/indexes/querying/searching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/sorting.mdx b/versioned_docs/version-5.4/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/versioned_docs/version-5.4/indexes/querying/sorting.mdx +++ b/versioned_docs/version-5.4/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/spatial.mdx b/versioned_docs/version-5.4/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/versioned_docs/version-5.4/indexes/querying/spatial.mdx +++ b/versioned_docs/version-5.4/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-5.4/indexes/querying/suggestions.mdx b/versioned_docs/version-5.4/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/versioned_docs/version-5.4/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-5.4/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/sorting-and-collation.mdx b/versioned_docs/version-5.4/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-5.4/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-5.4/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-5.4/indexes/stale-indexes.mdx b/versioned_docs/version-5.4/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-5.4/indexes/stale-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/storing-data-in-index.mdx b/versioned_docs/version-5.4/indexes/storing-data-in-index.mdx index d353ecb33e..3f3fe9512c 100644 --- a/versioned_docs/version-5.4/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-5.4/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/using-analyzers.mdx b/versioned_docs/version-5.4/indexes/using-analyzers.mdx index 4243e0369d..462e85f503 100644 --- a/versioned_docs/version-5.4/indexes/using-analyzers.mdx +++ b/versioned_docs/version-5.4/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/using-dynamic-fields.mdx b/versioned_docs/version-5.4/indexes/using-dynamic-fields.mdx index 010c89de9b..fe92642e46 100644 --- a/versioned_docs/version-5.4/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-5.4/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/indexes/using-term-vectors.mdx b/versioned_docs/version-5.4/indexes/using-term-vectors.mdx index 94ef7ada0b..819e006fd0 100644 --- a/versioned_docs/version-5.4/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-5.4/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/versioned_docs/version-5.4/indexes/what-are-indexes.mdx b/versioned_docs/version-5.4/indexes/what-are-indexes.mdx index 94d0413d6d..fd78bdc28a 100644 --- a/versioned_docs/version-5.4/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-5.4/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/server/_embedded-csharp.mdx b/versioned_docs/version-5.4/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/server/_embedded-csharp.mdx rename to versioned_docs/version-5.4/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-5.4/server/_embedded-java.mdx b/versioned_docs/version-5.4/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-5.4/server/_embedded-java.mdx rename to versioned_docs/version-5.4/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-5.4/server/embedded.mdx b/versioned_docs/version-5.4/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/versioned_docs/version-5.4/server/embedded.mdx +++ b/versioned_docs/version-5.4/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-5.4/server/extensions/_refresh-csharp.mdx b/versioned_docs/version-5.4/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/versioned_docs/version-5.4/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-5.4/server/extensions/_refresh-nodejs.mdx b/versioned_docs/version-5.4/server/extensions/_refresh-nodejs.mdx deleted file mode 100644 index f8a0a3d28c..0000000000 --- a/versioned_docs/version-5.4/server/extensions/_refresh-nodejs.mdx +++ /dev/null @@ -1,137 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - -## Overview - -To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. -This indicates when the document should be refreshed. - -This will cause the document to refresh **_only once_**! The refresh operation removes -the `@refresh` flag. - -The exact time that the document refreshes is not determined by the value of `@refresh` -- rather, the server refreshes documents at regular intervals determined by the Refresh -Configuration. The default interval is 60 seconds. - -Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) -to increment the same way it would after any other kind of update to the document. -This triggers any features that react to documents updating, including but not limited -to: - -* The document is re-indexed by any indexes that cover it. -* [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. -* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. - - - -## Examples - -#### Setting the refresh configuration for a database: - -To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. - - - -{`// Enable document refreshing and set the refresh interval to 5 minutes: -// ===================================================================== - -// Define the refresh configuration object -const refreshConfiguration = \{ - disabled: false, // Enable refreshing - refreshFrequencyInSec: 300 // Set interval to 5 minutes -\}; - -// Define the configure refresh operation, pass the configuration to set -const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); - -// Execute the operation by passing it to maintenance.send -await documentStore.maintenance.send(configureRefreshOp); -`} - - -#### Set a document to refresh 1 hour from now: - - - -{`// Setting a document to refresh after 1 hour: -// ==========================================+ - -// Load a document -const session = documentStore.openSession(); -const employee = await session.load("employees/1-A"); - -// Get the metadata of the document -const metadata = session.advanced.getMetadataFor(employee); - -// Set the "@refresh" metadata property with the refresh date in UTC format -const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) -metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); - -// Save the document -await session.saveChanges(); -`} - - - - - -## Syntax - - - -{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); -`} - - - -[//]: # (| Parameter | Type | Description |) -[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) -[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) -[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) -[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) - - - -{`// The refreshConfiguration object -\{ - disabled, - refreshFrequencyInSec -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| -| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | -| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-5.4/server/extensions/_expiration-csharp.mdx b/versioned_docs/version-5.4/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/server/extensions/_expiration-csharp.mdx rename to versioned_docs/version-5.4/server/extensions/content/_expiration-csharp.mdx diff --git a/versioned_docs/version-5.4/server/extensions/_expiration-nodejs.mdx b/versioned_docs/version-5.4/server/extensions/content/_expiration-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/server/extensions/_expiration-nodejs.mdx rename to versioned_docs/version-5.4/server/extensions/content/_expiration-nodejs.mdx diff --git a/versioned_docs/version-5.4/server/extensions/content/_refresh-csharp.mdx b/versioned_docs/version-5.4/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/versioned_docs/version-5.4/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-5.4/server/extensions/content/_refresh-nodejs.mdx b/versioned_docs/version-5.4/server/extensions/content/_refresh-nodejs.mdx new file mode 100644 index 0000000000..a4e68e0f7e --- /dev/null +++ b/versioned_docs/version-5.4/server/extensions/content/_refresh-nodejs.mdx @@ -0,0 +1,137 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + +## Overview + +To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. +This indicates when the document should be refreshed. + +This will cause the document to refresh **_only once_**! The refresh operation removes +the `@refresh` flag. + +The exact time that the document refreshes is not determined by the value of `@refresh` +- rather, the server refreshes documents at regular intervals determined by the Refresh +Configuration. The default interval is 60 seconds. + +Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) +to increment the same way it would after any other kind of update to the document. +This triggers any features that react to documents updating, including but not limited +to: + +* The document is re-indexed by any indexes that cover it. +* [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. +* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. + + + +## Examples + +#### Setting the refresh configuration for a database: + +To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. + + + +{`// Enable document refreshing and set the refresh interval to 5 minutes: +// ===================================================================== + +// Define the refresh configuration object +const refreshConfiguration = \{ + disabled: false, // Enable refreshing + refreshFrequencyInSec: 300 // Set interval to 5 minutes +\}; + +// Define the configure refresh operation, pass the configuration to set +const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); + +// Execute the operation by passing it to maintenance.send +await documentStore.maintenance.send(configureRefreshOp); +`} + + +#### Set a document to refresh 1 hour from now: + + + +{`// Setting a document to refresh after 1 hour: +// ==========================================+ + +// Load a document +const session = documentStore.openSession(); +const employee = await session.load("employees/1-A"); + +// Get the metadata of the document +const metadata = session.advanced.getMetadataFor(employee); + +// Set the "@refresh" metadata property with the refresh date in UTC format +const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) +metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); + +// Save the document +await session.saveChanges(); +`} + + + + + +## Syntax + + + +{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); +`} + + + +[//]: # (| Parameter | Type | Description |) +[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) +[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) +[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) +[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) + + + +{`// The refreshConfiguration object +\{ + disabled, + refreshFrequencyInSec +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| +| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | +| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-5.4/server/extensions/expiration.mdx b/versioned_docs/version-5.4/server/extensions/expiration.mdx index 3986525bb8..791e4136d6 100644 --- a/versioned_docs/version-5.4/server/extensions/expiration.mdx +++ b/versioned_docs/version-5.4/server/extensions/expiration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; -import ExpirationNodejs from './_expiration-nodejs.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; +import ExpirationNodejs from './content/_expiration-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/server/extensions/refresh.mdx b/versioned_docs/version-5.4/server/extensions/refresh.mdx index 8820271cfb..08eefe0c4f 100644 --- a/versioned_docs/version-5.4/server/extensions/refresh.mdx +++ b/versioned_docs/version-5.4/server/extensions/refresh.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; -import RefreshNodejs from './_refresh-nodejs.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; +import RefreshNodejs from './content/_refresh-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-5.4/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-5.4/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-5.4/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-5.4/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-5.4/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-5.4/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-5.4/server/storage/documents-compression.mdx b/versioned_docs/version-5.4/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-5.4/server/storage/documents-compression.mdx +++ b/versioned_docs/version-5.4/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/start/_test-driver-csharp.mdx b/versioned_docs/version-5.4/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-5.4/start/_test-driver-csharp.mdx rename to versioned_docs/version-5.4/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-5.4/start/_test-driver-java.mdx b/versioned_docs/version-5.4/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-5.4/start/_test-driver-java.mdx rename to versioned_docs/version-5.4/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-csharp.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-nodejs.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/versioned_docs/version-5.4/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/_overview-csharp.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/versioned_docs/version-5.4/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/_overview-nodejs.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index d2f9cd8940..0000000000 --- a/versioned_docs/version-5.4/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../..//client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-csharp.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/versioned_docs/version-5.4/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-csharp.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-nodejs.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..dee2af2555 --- /dev/null +++ b/versioned_docs/version-5.4/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../..//client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/existing-project.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/versioned_docs/version-5.4/start/guides/azure-functions/existing-project.mdx +++ b/versioned_docs/version-5.4/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/start/guides/azure-functions/overview.mdx b/versioned_docs/version-5.4/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/versioned_docs/version-5.4/start/guides/azure-functions/overview.mdx +++ b/versioned_docs/version-5.4/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-5.4/start/test-driver.mdx b/versioned_docs/version-5.4/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/versioned_docs/version-5.4/start/test-driver.mdx +++ b/versioned_docs/version-5.4/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-6.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-6.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-6.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-6.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-6.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-6.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-6.0/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-6.0/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-6.0/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-6.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-6.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-6.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-6.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-6.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-6.0/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-6.0/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-6.0/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-6.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-6.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-6.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx b/versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx rename to versioned_docs/version-6.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-6.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 668d999b7d..5c6923b919 100644 --- a/versioned_docs/version-6.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-6.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchNodejs from './_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchNodejs from './content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/commands/_overview-csharp.mdx b/versioned_docs/version-6.0/client-api/commands/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/_overview-csharp.mdx rename to versioned_docs/version-6.0/client-api/commands/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/_overview-java.mdx b/versioned_docs/version-6.0/client-api/commands/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/_overview-java.mdx rename to versioned_docs/version-6.0/client-api/commands/content/_overview-java.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/_overview-nodejs.mdx b/versioned_docs/version-6.0/client-api/commands/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/_overview-nodejs.mdx rename to versioned_docs/version-6.0/client-api/commands/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_delete-nodejs.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_delete-nodejs.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_delete-php.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_delete-php.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_delete-php.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_delete-python.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_delete-python.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_delete-python.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_get-php.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_get-php.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_get-php.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_get-python.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_get-python.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_get-python.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_put-nodejs.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_put-nodejs.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_put-php.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_put-php.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_put-php.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/_put-python.mdx b/versioned_docs/version-6.0/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/commands/documents/_put-python.mdx rename to versioned_docs/version-6.0/client-api/commands/documents/content/_put-python.mdx diff --git a/versioned_docs/version-6.0/client-api/commands/documents/delete.mdx b/versioned_docs/version-6.0/client-api/commands/documents/delete.mdx index 61091b815c..a88bb5f5db 100644 --- a/versioned_docs/version-6.0/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-6.0/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/commands/documents/get.mdx b/versioned_docs/version-6.0/client-api/commands/documents/get.mdx index 1e303a3f73..325076a4dc 100644 --- a/versioned_docs/version-6.0/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-6.0/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/commands/documents/put.mdx b/versioned_docs/version-6.0/client-api/commands/documents/put.mdx index ee9e70143c..9c8ba28480 100644 --- a/versioned_docs/version-6.0/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-6.0/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/commands/overview.mdx b/versioned_docs/version-6.0/client-api/commands/overview.mdx index dd0aca1a6c..744fb40071 100644 --- a/versioned_docs/version-6.0/client-api/commands/overview.mdx +++ b/versioned_docs/version-6.0/client-api/commands/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-6.0/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-6.0/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/conventions.mdx b/versioned_docs/version-6.0/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/versioned_docs/version-6.0/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/deserialization.mdx b/versioned_docs/version-6.0/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-6.0/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-6.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-6.0/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to versioned_docs/version-6.0/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/versioned_docs/version-6.0/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-6.0/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/versioned_docs/version-6.0/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/configuration/serialization.mdx b/versioned_docs/version-6.0/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-6.0/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-6.0/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-6.0/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-6.0/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/_creating-document-store-java.mdx b/versioned_docs/version-6.0/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-6.0/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-6.0/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-6.0/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-6.0/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-6.0/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-6.0/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-6.0/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-6.0/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-6.0/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-6.0/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-6.0/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/creating-document-store.mdx b/versioned_docs/version-6.0/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-6.0/client-api/creating-document-store.mdx +++ b/versioned_docs/version-6.0/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index cd09e4587d..0000000000 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index c2d1857b87..0000000000 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,134 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 12e6eedbd2..0000000000 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/concurrent-subscriptions.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_examples-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..30fd3f7254 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..aaa26a16f7 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,134 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..d82e45f68c --- /dev/null +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_examples-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to versioned_docs/version-6.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-6.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 881ea78195..16791e745a 100644 --- a/versioned_docs/version-6.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-6.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-6.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-6.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-6.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-6.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-6.0/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-6.0/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-6.0/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-6.0/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-6.0/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-6.0/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-nodejs.mdx b/versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to versioned_docs/version-6.0/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-6.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-6.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-6.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-6.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-6.0/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-6.0/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/versioned_docs/version-6.0/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-6.0/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-6.0/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-6.0/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-6.0/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/net-client-versions.mdx b/versioned_docs/version-6.0/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-6.0/client-api/net-client-versions.mdx +++ b/versioned_docs/version-6.0/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_delete-attachment-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_get-attachment-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_get-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/attachments/_put-attachment-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/attachments/content/_put-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/delete-attachment.mdx index b1b8dc0862..b4a5d42046 100644 --- a/versioned_docs/version-6.0/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-6.0/client-api/operations/attachments/delete-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; -import DeleteAttachmentNodejs from './_delete-attachment-nodejs.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; +import DeleteAttachmentNodejs from './content/_delete-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/get-attachment.mdx index dfbe7f67bf..16af9d26fc 100644 --- a/versioned_docs/version-6.0/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-6.0/client-api/operations/attachments/get-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; -import GetAttachmentNodejs from './_get-attachment-nodejs.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; +import GetAttachmentNodejs from './content/_get-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-6.0/client-api/operations/attachments/put-attachment.mdx index 7d63f1af0f..19a6aa8702 100644 --- a/versioned_docs/version-6.0/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-6.0/client-api/operations/attachments/put-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; -import PutAttachmentNodejs from './_put-attachment-nodejs.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; +import PutAttachmentNodejs from './content/_put-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-php.mdx b/versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-php.mdx rename to versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-python.mdx b/versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/common/_delete-by-query-python.mdx rename to versioned_docs/version-6.0/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-6.0/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/versioned_docs/version-6.0/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-6.0/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-php.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-php.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-python.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_overview-python.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_overview-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 5cd2b2f3bb..4dbcb13cc5 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; -import DeleteCompareExchangeValueNodejs from './_delete-compare-exchange-value-nodejs.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueNodejs from './content/_delete-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 5a3faf4c6d..797adb1e32 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; -import GetCompareExchangeValueNodejs from './_get-compare-exchange-value-nodejs.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueNodejs from './content/_get-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index 3cd524682d..7371593482 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; -import GetCompareExchangeValuesNodejs from './_get-compare-exchange-values-nodejs.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesNodejs from './content/_get-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/include-compare-exchange.mdx index ef602a655c..c2da54868f 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; -import IncludeCompareExchangeNodejs from './_include-compare-exchange-nodejs.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeNodejs from './content/_include-compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/overview.mdx index 66ee3a1273..d63e1a098c 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "php"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-6.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index ed5ae625f9..fe51a43af8 100644 --- a/versioned_docs/version-6.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-6.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; -import PutCompareExchangeValueNodejs from './_put-compare-exchange-value-nodejs.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueNodejs from './content/_put-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/_what-are-operations-php.mdx b/versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/_what-are-operations-php.mdx rename to versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/_what-are-operations-python.mdx b/versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/_what-are-operations-python.mdx rename to versioned_docs/version-6.0/client-api/operations/content/_what-are-operations-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-php.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_counter-batch-php.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_get-counters-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_get-counters-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/_get-counters-php.mdx b/versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/counters/_get-counters-php.mdx rename to versioned_docs/version-6.0/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-6.0/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/versioned_docs/version-6.0/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-6.0/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-6.0/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/versioned_docs/version-6.0/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-6.0/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to versioned_docs/version-6.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-6.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index dbbb74bb3e..81f30c05e4 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 8870c1da85..418075a390 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 715c28bc20..e48caa5360 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/_get-stats-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/add-etl.mdx index b849a0157c..83767b75af 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/get-identities.mdx index 0a5fdffa45..5bc99a1074 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-6.0/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_set-based-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_set-based-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/_single-document-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/patching/_single-document-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/patching/set-based.mdx b/versioned_docs/version-6.0/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/versioned_docs/version-6.0/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-6.0/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/patching/single-document.mdx b/versioned_docs/version-6.0/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/versioned_docs/version-6.0/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-6.0/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-php.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-php.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-python.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_add-database-node-python.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-php.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-php.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-python.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_compact-database-python.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/create-database.mdx index 06626431e0..59effdb582 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-6.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-6.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/operations/what-are-operations.mdx b/versioned_docs/version-6.0/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/versioned_docs/version-6.0/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-6.0/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-6.0/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-6.0/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/security/deserialization-security.mdx b/versioned_docs/version-6.0/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-6.0/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-6.0/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index 811678c09d..0000000000 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - session.Store(new User(), "users/johndoe"); - session.SaveChanges(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var session1 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var session2 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = session1.Load("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = session2.Load("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - session1.SaveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - session2.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - await asyncSession.SaveChangesAsync(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var asyncSession1 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var asyncSession2 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // asyncSession1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - await asyncSession1.SaveChangesAsync(); - - // asyncSession2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - await asyncSession2.SaveChangesAsync(); -} -`} - - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - session.Store(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`Load` the document into the session before storing it** - - even if the document is expected to be new. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating a new one or modifying if already exists - var user = session.Load("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - session.Store(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating or updating - var user = await asyncSession.LoadAsync("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - await asyncSession.StoreAsync(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index d9ae1ff263..0000000000 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,261 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session: -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two concurrent cluster-wide sessions: -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// Both sessions load the same document: -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 saves its changes first — -// this increments the Raft index of the associated atomic guard. -await session1.saveChanges(); - -// session2 tries to save using an outdated atomic guard version -// and fails with a ConcurrencyException. -await session2.saveChanges(); -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`const session = documentStore.openSession(\{ - // Open a cluster-wide session - transactionMode: "ClusterWide" -\}); - -// Load the user document BEFORE creating or updating -const user = await session.load("users/johndoe"); - -if (!user) \{ - // Document doesn't exist => create a new document - const newUser = \{ - name: "John Doe", - // ... initialize other properties - \}; - - // Store the new user document in the session - await session.store(newUser, "users/johndoe"); - -\} else \{ - // Document exists => apply your modifications - user.name = "New name"; - // ... make any other updates - - // No need to call store() again - // RavenDB tracks changes on loaded entities -\} - -// Commit your changes -await session.saveChanges(); -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx deleted file mode 100644 index aee89e6ab0..0000000000 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx +++ /dev/null @@ -1,276 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`// Open a cluster-wide session: -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // An atomic-guard is now automatically created for the new document "users/johndoe". - $session->saveChanges(); -\} finally \{ - $session->close(); -\} - -// Open two concurrent cluster-wide sessions: - -$sessionOptions1 = new SessionOptions(); -$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); - -$session1 = $store->openSession($sessionOptions1); -try \{ - $sessionOptions2 = new SessionOptions(); - $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); - $session2 = $store->openSession($sessionOptions2); - - try \{ - // Both sessions load the same document: - var $loadedUser1 = $session1->load(User::class, "users/johndoe"); - $loadedUser1->setName("jindoe"); - - $loadedUser2 = $session2->load(User::class, "users/johndoe"); - $loadedUser2->setName("jandoe"); - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - $session1->saveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - $session2->saveChanges(); - \} finally \{ - $session2->close(); - \} - -\} finally \{ - $session1->close(); -\} -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); -$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // No atomic-guard will be created upon saveChanges - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`// Open a cluster-wide session -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); -try \{ - // Load the user document BEFORE creating or updating - $user = $session->load(User::class, "users/johndoe"); - - if ($user === null) \{ - // Document doesn't exist => create a new document: - $newUser = new User(); - $newUser->setName("John Doe"); - // ... initialize other properties - - // Store the new user document in the session - $session->store($newUser, "users/johndoe"); - \} else \{ - // Document exists => apply your modifications: - $user->setName("New name"); - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - \} - - // Commit your changes - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx deleted file mode 100644 index e650aac9bf..0000000000 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx +++ /dev/null @@ -1,251 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`with store.open_session( - # Open a cluster-wide session: - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session: - session.store(User(), "users/johndoe") - session.save_changes() - # An atomic-guard is now automatically created for the new document "users/johndoe" - -# Open two concurrent cluster-wide sessions: -with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session1: - with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) - ) as session2: - # Both sessions load the same document: - loaded_user_1 = session1.load("users/johndoe", User) - loaded_user_1.name = "jindoe" - loaded_user_2 = session2.load("users/johndoe", User) - loaded_user_2.name = "jandoe" - - # session1 saves its changes first — - # this increments the Raft index of the associated atomic guard. - session1.save_changes() - - # session2 tries to save using an outdated atomic guard version - # and fails with a ConcurrencyException. - session2.save_changes() -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`with store.open_session( - # Open a cluster-wide session - session_options=SessionOptions( - transaction_mode=TransactionMode.CLUSTER_WIDE, - disable_atomic_document_writes_in_cluster_wide_transaction=True, - ) -) as session: - session.store(User(), "users/johndoe") - - # No atomic-guard will be created upon save_changes - session.save_changes() -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`with store.open_session( - session_options=SessionOptions( - # Open a cluster-wide session - transaction_mode=TransactionMode.CLUSTER_WIDE - ) -) as session: - # Load the user document BEFORE creating or updating - user = session.load("users/johndoe", User) - - if user is None: - # Document doesn't exist => create a new document - new_user = User() - new_user.name = "John Doe" - # ... initialize other properties - - # Store the new user document in the session - session.store(new_user, "users/johndoe") - else: - # Document exists => apply your modifications - user.name = "New name" - # ... make any other updates - - # No need to call store() again - # RavenDB tracks changes on loaded entities - - # Commit your changes - session.save_changes() -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/atomic-guards.mdx index 8e705c3a32..29ace602dc 100644 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsPython from './_atomic-guards-python.mdx'; -import AtomicGuardsPhp from './_atomic-guards-php.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsPython from './content/_atomic-guards-python.mdx'; +import AtomicGuardsPhp from './content/_atomic-guards-php.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/compare-exchange.mdx index d4bdc9d5da..a98b9edf99 100644 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangePython from './_compare-exchange-python.mdx'; -import CompareExchangePhp from './_compare-exchange-php.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangePython from './content/_compare-exchange-python.mdx'; +import CompareExchangePhp from './content/_compare-exchange-php.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..9c603424ba --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + session.Store(new User(), "users/johndoe"); + session.SaveChanges(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var session1 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var session2 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = session1.Load("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = session2.Load("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + session1.SaveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + session2.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + await asyncSession.SaveChangesAsync(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var asyncSession1 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var asyncSession2 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // asyncSession1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + await asyncSession1.SaveChangesAsync(); + + // asyncSession2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + await asyncSession2.SaveChangesAsync(); +} +`} + + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + session.Store(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`Load` the document into the session before storing it** - + even if the document is expected to be new. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating a new one or modifying if already exists + var user = session.Load("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + session.Store(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating or updating + var user = await asyncSession.LoadAsync("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + await asyncSession.StoreAsync(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..2825373609 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,261 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session: +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two concurrent cluster-wide sessions: +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// Both sessions load the same document: +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 saves its changes first — +// this increments the Raft index of the associated atomic guard. +await session1.saveChanges(); + +// session2 tries to save using an outdated atomic guard version +// and fails with a ConcurrencyException. +await session2.saveChanges(); +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`const session = documentStore.openSession(\{ + // Open a cluster-wide session + transactionMode: "ClusterWide" +\}); + +// Load the user document BEFORE creating or updating +const user = await session.load("users/johndoe"); + +if (!user) \{ + // Document doesn't exist => create a new document + const newUser = \{ + name: "John Doe", + // ... initialize other properties + \}; + + // Store the new user document in the session + await session.store(newUser, "users/johndoe"); + +\} else \{ + // Document exists => apply your modifications + user.name = "New name"; + // ... make any other updates + + // No need to call store() again + // RavenDB tracks changes on loaded entities +\} + +// Commit your changes +await session.saveChanges(); +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx new file mode 100644 index 0000000000..c6fcf1e501 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx @@ -0,0 +1,276 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`// Open a cluster-wide session: +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // An atomic-guard is now automatically created for the new document "users/johndoe". + $session->saveChanges(); +\} finally \{ + $session->close(); +\} + +// Open two concurrent cluster-wide sessions: + +$sessionOptions1 = new SessionOptions(); +$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); + +$session1 = $store->openSession($sessionOptions1); +try \{ + $sessionOptions2 = new SessionOptions(); + $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); + $session2 = $store->openSession($sessionOptions2); + + try \{ + // Both sessions load the same document: + var $loadedUser1 = $session1->load(User::class, "users/johndoe"); + $loadedUser1->setName("jindoe"); + + $loadedUser2 = $session2->load(User::class, "users/johndoe"); + $loadedUser2->setName("jandoe"); + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + $session1->saveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + $session2->saveChanges(); + \} finally \{ + $session2->close(); + \} + +\} finally \{ + $session1->close(); +\} +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); +$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // No atomic-guard will be created upon saveChanges + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`// Open a cluster-wide session +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); +try \{ + // Load the user document BEFORE creating or updating + $user = $session->load(User::class, "users/johndoe"); + + if ($user === null) \{ + // Document doesn't exist => create a new document: + $newUser = new User(); + $newUser->setName("John Doe"); + // ... initialize other properties + + // Store the new user document in the session + $session->store($newUser, "users/johndoe"); + \} else \{ + // Document exists => apply your modifications: + $user->setName("New name"); + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + \} + + // Commit your changes + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx new file mode 100644 index 0000000000..489119ff63 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx @@ -0,0 +1,251 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`with store.open_session( + # Open a cluster-wide session: + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session: + session.store(User(), "users/johndoe") + session.save_changes() + # An atomic-guard is now automatically created for the new document "users/johndoe" + +# Open two concurrent cluster-wide sessions: +with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session1: + with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) + ) as session2: + # Both sessions load the same document: + loaded_user_1 = session1.load("users/johndoe", User) + loaded_user_1.name = "jindoe" + loaded_user_2 = session2.load("users/johndoe", User) + loaded_user_2.name = "jandoe" + + # session1 saves its changes first — + # this increments the Raft index of the associated atomic guard. + session1.save_changes() + + # session2 tries to save using an outdated atomic guard version + # and fails with a ConcurrencyException. + session2.save_changes() +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`with store.open_session( + # Open a cluster-wide session + session_options=SessionOptions( + transaction_mode=TransactionMode.CLUSTER_WIDE, + disable_atomic_document_writes_in_cluster_wide_transaction=True, + ) +) as session: + session.store(User(), "users/johndoe") + + # No atomic-guard will be created upon save_changes + session.save_changes() +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`with store.open_session( + session_options=SessionOptions( + # Open a cluster-wide session + transaction_mode=TransactionMode.CLUSTER_WIDE + ) +) as session: + # Load the user document BEFORE creating or updating + user = session.load("users/johndoe", User) + + if user is None: + # Document doesn't exist => create a new document + new_user = User() + new_user.name = "John Doe" + # ... initialize other properties + + # Store the new user document in the session + session.store(new_user, "users/johndoe") + else: + # Document exists => apply your modifications + user.name = "New name" + # ... make any other updates + + # No need to call store() again + # RavenDB tracks changes on loaded entities + + # Commit your changes + session.save_changes() +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-php.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-php.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-python.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_compare-exchange-python.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-php.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-php.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-python.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/cluster-transaction/_overview-python.mdx rename to versioned_docs/version-6.0/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-6.0/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/versioned_docs/version-6.0/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-6.0/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to versioned_docs/version-6.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-6.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/versioned_docs/version-6.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-6.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_deleting-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_deleting-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_deleting-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_deleting-entities-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_deleting-entities-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_deleting-entities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_loading-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_loading-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_loading-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_loading-entities-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_loading-entities-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_loading-entities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_opening-a-session-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_opening-a-session-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_opening-a-session-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_opening-a-session-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_opening-a-session-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_opening-a-session-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_saving-changes-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_saving-changes-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_saving-changes-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_saving-changes-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_saving-changes-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_saving-changes-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_storing-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_storing-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_storing-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_storing-entities-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_storing-entities-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_storing-entities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_updating-entities-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_updating-entities-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_updating-entities-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_updating-entities-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_updating-entities-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_updating-entities-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to versioned_docs/version-6.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/deleting-entities.mdx b/versioned_docs/version-6.0/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/versioned_docs/version-6.0/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-6.0/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-6.0/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-6.0/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-6.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-6.0/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-document-exists-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_clear-a-session-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_defer-operations-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-current-session-node-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-counters-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-php.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-php.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-python.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_refresh-entity-python.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-6.0/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-6.0/client-api/session/how-to/evict-entity-from-a-session.mdx index 958fc3efc6..b8527408ff 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/get-tracked-entities.mdx b/versioned_docs/version-6.0/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/get-tracked-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-6.0/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-6.0/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-6.0/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-6.0/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-6.0/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-6.0/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/loading-entities.mdx b/versioned_docs/version-6.0/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/versioned_docs/version-6.0/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/opening-a-session.mdx b/versioned_docs/version-6.0/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/versioned_docs/version-6.0/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-6.0/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 76701c04da..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,962 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index f63a3d807a..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,514 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - -* Note the following difference between the underlying search engines: - - * When using __Lucene__: - This metadata property is always available in the results. - - * When using __Corax__: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index f970fa79dd..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,539 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) # todo gracjan: check if its possible to order by again without then_by - # todo reeb: skip this example for now, we'll get back to it later on - # A secondary sort can be applied -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 2767086d97..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index ca6f981b62..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,465 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -|--------------|-----------------------|-------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode ` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-count-query-results-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-customize-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..a3f3e8abc4 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,962 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..3229d3c59f --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,514 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + +* Note the following difference between the underlying search engines: + + * When using __Lucene__: + This metadata property is always available in the results. + + * When using __Corax__: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..e127cbf432 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,539 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) # todo gracjan: check if its possible to order by again without then_by + # todo reeb: skip this example for now, we'll get back to it later on + # A secondary sort can be applied +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-project-query-results-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-intersect-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..1d4b9221d7 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f912ddf78b --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,465 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +|--------------|-----------------------|-------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode ` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/_sort-query-results-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index ced793543f..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 90c08b9c95..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index 82050a7150..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -The `QueryTimings` object will be filled with the timings when the query returns. - -| `QueryTimings` | | | -|------------------|-----------------------------|---------------------------------------------------| -| __durationInMs__ | `long` | Total duration | -| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 2594955761..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,106 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 447455323e..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index a24ff39584..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..54a96307a9 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..87f6efdabe --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..dde738eb47 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +The `QueryTimings` object will be filled with the timings when the query returns. + +| `QueryTimings` | | | +|------------------|-----------------------------|---------------------------------------------------| +| __durationInMs__ | `long` | Total duration | +| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..04c49f9a7d --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,106 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..ff61a93e87 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..ed2089f0f5 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-6.0/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-project-query-results.mdx index 005a01c964..505ff9b85d 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-6.0/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/sort-query-results.mdx index a34e918743..26b8cb85a3 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/sort-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 4d6da16a2d..0000000000 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,373 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) - -# todo reeb & gracjan: lets implement it after 5.4 release -# i have a perfect ticket for that -# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_full-text-search-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..0bf2fc548a --- /dev/null +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,373 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) + +# todo reeb & gracjan: lets implement it after 5.4 release +# i have a perfect ticket for that +# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_proximity-search-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-php.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-php.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-python.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/session/querying/text-search/_using-regex-python.mdx rename to versioned_docs/version-6.0/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-6.0/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/versioned_docs/version-6.0/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-6.0/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/saving-changes.mdx b/versioned_docs/version-6.0/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/versioned_docs/version-6.0/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-6.0/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/storing-entities.mdx b/versioned_docs/version-6.0/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/versioned_docs/version-6.0/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/updating-entities.mdx b/versioned_docs/version-6.0/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/versioned_docs/version-6.0/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-6.0/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-6.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/versioned_docs/version-6.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-6.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-6.0/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-6.0/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-6.0/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/setting-up-default-database.mdx b/versioned_docs/version-6.0/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-6.0/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-6.0/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-6.0/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-6.0/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-6.0/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-6.0/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-6.0/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/client-api/what-is-a-document-store.mdx b/versioned_docs/version-6.0/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-6.0/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-6.0/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/bulk-insert.mdx b/versioned_docs/version-6.0/document-extensions/attachments/bulk-insert.mdx index c763b6a3ca..296538d2fa 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/bulk-insert.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/bulk-insert.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BulkInsertCsharp from './_bulk-insert-csharp.mdx'; -import BulkInsertPython from './_bulk-insert-python.mdx'; -import BulkInsertNodejs from './_bulk-insert-nodejs.mdx'; +import BulkInsertCsharp from './content/_bulk-insert-csharp.mdx'; +import BulkInsertPython from './content/_bulk-insert-python.mdx'; +import BulkInsertNodejs from './content/_bulk-insert-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_bulk-insert-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_bulk-insert-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-php.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-php.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_copying-moving-renaming-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_copying-moving-renaming-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_deleting-php.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_deleting-php.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_deleting-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_deleting-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_deleting-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_indexing-php.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_indexing-php.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_indexing-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_indexing-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_loading-php.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_loading-php.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_loading-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_loading-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_loading-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_loading-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_storing-php.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_storing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_storing-php.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_storing-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_storing-python.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_storing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_storing-python.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_storing-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-6.0/document-extensions/attachments/copying-moving-renaming.mdx index 5d9756c7ff..dd66ad7797 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; -import CopyingMovingRenamingPython from './_copying-moving-renaming-python.mdx'; -import CopyingMovingRenamingPhp from './_copying-moving-renaming-php.mdx'; -import CopyingMovingRenamingNodejs from './_copying-moving-renaming-nodejs.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingPython from './content/_copying-moving-renaming-python.mdx'; +import CopyingMovingRenamingPhp from './content/_copying-moving-renaming-php.mdx'; +import CopyingMovingRenamingNodejs from './content/_copying-moving-renaming-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/deleting.mdx b/versioned_docs/version-6.0/document-extensions/attachments/deleting.mdx index 412aa66a67..604c4058e7 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/deleting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingPython from './_deleting-python.mdx'; -import DeletingPhp from './_deleting-php.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingPython from './content/_deleting-python.mdx'; +import DeletingPhp from './content/_deleting-php.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/indexing.mdx b/versioned_docs/version-6.0/document-extensions/attachments/indexing.mdx index d49e97610c..8fca84b22e 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/loading.mdx b/versioned_docs/version-6.0/document-extensions/attachments/loading.mdx index b845db6865..6c82d701c2 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/storing.mdx b/versioned_docs/version-6.0/document-extensions/attachments/storing.mdx index 5e877c3b82..cb3e3b93d1 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/storing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringPython from './_storing-python.mdx'; -import StoringPhp from './_storing-php.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringPython from './content/_storing-python.mdx'; +import StoringPhp from './content/_storing-php.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-6.0/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-6.0/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-6.0/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_counters-and-other-features-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_create-or-modify-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_delete-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_delete-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_delete-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_delete-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_delete-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_delete-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_delete-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_delete-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_including-counters-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_including-counters-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_including-counters-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_including-counters-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_including-counters-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_including-counters-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_including-counters-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_including-counters-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_including-counters-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_including-counters-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_including-counters-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_indexing-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_indexing-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_indexing-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_indexing-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_overview-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_overview-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_overview-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_overview-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_overview-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_overview-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_overview-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-php.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-php.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-python.mdx b/versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/counters/_retrieve-counter-values-python.mdx rename to versioned_docs/version-6.0/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-6.0/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-6.0/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/delete.mdx b/versioned_docs/version-6.0/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/including-counters.mdx b/versioned_docs/version-6.0/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/including-counters.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/indexing.mdx b/versioned_docs/version-6.0/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/overview.mdx b/versioned_docs/version-6.0/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-6.0/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/versioned_docs/version-6.0/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-6.0/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 4365c1079c..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,321 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index 8b480d9db1..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,318 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_overview-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 0dd4ed178c..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,281 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 1906658a54..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index 3c8783a8ad..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index d42399f08e..0000000000 --- a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/_overview-python.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_counting-python.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_including-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-php.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/client-api/session/_loading-python.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..0f66fc334b --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,321 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..b57988e8d8 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,318 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..63987fad60 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,281 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..335c0a220b --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6bf087d689 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..ab3a281b0b --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.0/document-extensions/revisions/overview.mdx b/versioned_docs/version-6.0/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/overview.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-6.0/document-extensions/revisions/revisions-and-other-features.mdx index dd80b671dc..38db72b2c8 100644 --- a/versioned_docs/version-6.0/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-6.0/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 509e667890..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,301 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series. -`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 782549d0c2..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,258 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series. -`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index eaeda8b14c..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,335 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------|------|-------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. -`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index 64b9871a61..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,310 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------|------|-------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. -`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/javascript-support.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/named-time-series-values.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/get.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/get.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/patch.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/overview.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/overview.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/append.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/append.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_append-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/delete.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/delete.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-names.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/overview.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/patch.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/patch.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/querying.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/querying.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_design-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_design-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_design-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_design-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_indexing-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_indexing-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_indexing-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_indexing-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_indexing-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_indexing-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/_indexing-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/_indexing-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..42b2a7615a --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,301 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series. +`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..fdd555002e --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,258 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series. +`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..88a235e310 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,335 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------|------|-------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. +`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..a88dec2de0 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,310 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------|------|-------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series. +`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/design.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/design.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/indexing.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/indexing.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 2e1013e32c..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,318 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index ac0ea992b5..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,338 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index 83305e53a8..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,287 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index f5f7118bfa..0000000000 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,285 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -
- -| With Time Series Function | Without Time Series Function | -|----------------------------|-------------------------------| -| -```javascript -{`// declare the time series function: -declare timeseries ts(jogger) \{ - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -\} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -`} -``` -| -```javascript -{`from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -`} -``` - | - - - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/choosing-query-range.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_filtering-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..2f6b2c7fae --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,318 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..5f7217380a --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,338 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..50a24159be --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,287 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..6664e2ef48 --- /dev/null +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,285 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| +```javascript +{`// declare the time series function: +declare timeseries ts(jogger) \{ + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +\} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +`} +``` +| +```javascript +{`from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +`} +``` + | + + + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-php.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-python.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to versioned_docs/version-6.0/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/filtering.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/filtering.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/overview-and-syntax.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/querying/using-indexes.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/querying/using-indexes.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/rollup-and-retention.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/rollup-and-retention.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/document-extensions/timeseries/time-series-and-other-features.mdx b/versioned_docs/version-6.0/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/versioned_docs/version-6.0/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/versioned_docs/version-6.0/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-6.0/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-6.0/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-6.0/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_index-query-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_index-query-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_query-result-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_query-result-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/_stream-result-csharp.mdx b/versioned_docs/version-6.0/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-6.0/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-6.0/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-6.0/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-6.0/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/counters-batch-command-data.mdx b/versioned_docs/version-6.0/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-6.0/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/delete-command-data.mdx b/versioned_docs/version-6.0/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-6.0/glossary/delete-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-6.0/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-6.0/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/index-query.mdx b/versioned_docs/version-6.0/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-6.0/glossary/index-query.mdx +++ b/versioned_docs/version-6.0/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/move-attachment-command-data.mdx b/versioned_docs/version-6.0/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-6.0/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/patch-command-data.mdx b/versioned_docs/version-6.0/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-6.0/glossary/patch-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/put-command-data.mdx b/versioned_docs/version-6.0/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-6.0/glossary/put-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-6.0/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-6.0/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-6.0/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/query-result.mdx b/versioned_docs/version-6.0/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-6.0/glossary/query-result.mdx +++ b/versioned_docs/version-6.0/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/stream-query-statistics.mdx b/versioned_docs/version-6.0/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-6.0/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-6.0/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-6.0/glossary/stream-result.mdx b/versioned_docs/version-6.0/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-6.0/glossary/stream-result.mdx +++ b/versioned_docs/version-6.0/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-6.0/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-6.0/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-nested-data-php.mdx b/versioned_docs/version-6.0/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-nested-data-python.mdx b/versioned_docs/version-6.0/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-6.0/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-6.0/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-related-documents-php.mdx b/versioned_docs/version-6.0/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.0/indexes/_indexing-related-documents-python.mdx b/versioned_docs/version-6.0/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/versioned_docs/version-6.0/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-6.0/indexes/_using-analyzers-csharp.mdx deleted file mode 100644 index 0c33a1d29f..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-analyzers-csharp.mdx +++ /dev/null @@ -1,691 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - - 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - - 2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - use the `Analyzers.Add()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`// The index definition -public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string[] Tags { get; set; } - public string Content { get; set; } - } - - public BlogPosts_ByTagsAndContent() - { - Map = posts => from post in posts - select new IndexEntry() - { - Tags = post.Tags, - Content = post.Content - }; - - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - Analyzers.Add(x => x.Content, - typeof(SnowballAnalyzer).AssemblyQualifiedName); - } -} -`} - - - - -{`// The index definition -var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") -{ - Map = posts => from post in posts - select new {post.Tags, post.Content}, - - Analyzers = - { - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - {x => x.Tags, "SimpleAnalyzer"}, - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} - } -}.ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `FieldIndexing.Exact` - * `FieldIndexing.Search` - * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`public class BlogPosts_ByContent : AbstractIndexCreationTask -\{ - public BlogPosts_ByContent() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Search' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.Search); - - // => Index-field 'Content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `FieldIndexing.Exact`, - RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask -\{ - public Employees_ByFirstAndLastName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName, - FirstName = employee.FirstName - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Exact' on index-field 'FirstName' - Indexes.Add(x => x.FirstName, FieldIndexing.Exact); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstName : AbstractIndexCreationTask -\{ - public Employees_ByFirstName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName - \}; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`public class BlogPosts_ByTitle : AbstractIndexCreationTask -\{ - public BlogPosts_ByTitle() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.No' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.No); - - // Set 'FieldStorage.Yes' to store the original content of field 'Content' - // in the index - Stores.Add(x => x.Content, FieldStorage.Yes); - - // => No analyzer will process field 'Content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public class AnalyzerDefinition -\{ - // Name of the analyzer - public string Name \{ get; set; \} - - // C# source-code of the analyzer - public string Code \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`// Define the put analyzer operation: -var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition -\{ - // The name must be same as the analyzer's class name - Name = "MyAnalyzer", - - Code = @" - using System.IO; - using Lucene.Net.Analysis; - using Lucene.Net.Analysis.Standard; - - namespace MyAnalyzer - \{ - public class MyAnalyzer : Lucene.Net.Analysis.Analyzer - \{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - throw new CodeOmitted(); - \} - \} - \}" -\}); - -// Deploy the analyzer: -store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-6.0/indexes/_using-analyzers-nodejs.mdx deleted file mode 100644 index b120b39ea1..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-analyzers-nodejs.mdx +++ /dev/null @@ -1,655 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - -1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - -2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - set the `analyze()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content - })\`; - - // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer - this.analyze("tags", "SimpleAnalyzer"); - - // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer - this.analyze("content", "Raven.Sample.SnowballAnalyzer"); - } -} -`} - - - - -{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); -builder.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content -})\`; -builder.analyzersStrings["tags"] = "SimpleAnalyzer"; -builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; - -await store.maintenance - .send(new PutIndexesOperation( - builder.toIndexDefinition(store.conventions))); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `Exact` - * `Search` - * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Search' on index-field 'content' - this.index("content", "Search"); - - // => Index-field 'content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FirstName = employee.FirstName " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Exact' on index-field 'FirstName' - this.index("FirstName", "Exact"); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName" + - "\})"; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'No' on index-field 'content' - this.index("content", "No"); - - // Set 'Yes' to store the original content of field 'content' in the index - this.store("content", "Yes"); - - // => No analyzer will process field 'content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`const analyzerDefinition = \{ - name: "analyzerName", - code: "code" -\}; -`} - - - -| Parameter | Type | Description | -|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`const analyzerDefinition = \{ - name: "MyAnalyzer", - code: "using System.IO;\\n" + - "using Lucene.Net.Analysis;\\n" + - "using Lucene.Net.Analysis.Standard;\\n" + - "\\n" + - "namespace MyAnalyzer\\n" + - "\{\\n" + - " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + - " \{\\n" + - " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + - " \{\\n" + - " throw new CodeOmitted();\\n" + - " \}\\n" + - " \}\\n" + - "\}\\n" -\}; - -await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-6.0/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index af290517e0..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-6.0/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 035114b307..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,488 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-6.0/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 1cdf1853fa..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,564 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`false` - will set `FieldStorage.No` (default value) -`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`null` - `FieldIndexing.Default` (default value) -`false` - `FieldIndexing.Exact` -`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-php.mdx b/versioned_docs/version-6.0/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index f02a86fa8a..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,568 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | | | -|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`False` - will set `FieldStorage.NO` (default value) -`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`None` - `FieldIndexing.Default` (default value) -`False` - `FieldIndexing.Exact` -`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-python.mdx b/versioned_docs/version-6.0/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index 0490bf84df..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,520 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | | | -|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field -The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) - -`False` - will set `FieldStorage.NO` (default value) -`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) - -`None` - `FieldIndexing.Default` (default value) -`False` - `FieldIndexing.Exact` -`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.0/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-6.0/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/versioned_docs/version-6.0/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/versioned_docs/version-6.0/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index f784c64ebd..0000000000 --- a/versioned_docs/version-6.0/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.0/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-6.0/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index bc0dfd5fef..0000000000 --- a/versioned_docs/version-6.0/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.0/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/versioned_docs/version-6.0/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.0/indexes/_what-are-indexes-php.mdx b/versioned_docs/version-6.0/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/versioned_docs/version-6.0/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.0/indexes/_what-are-indexes-python.mdx b/versioned_docs/version-6.0/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/versioned_docs/version-6.0/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.0/indexes/boosting.mdx b/versioned_docs/version-6.0/indexes/boosting.mdx index 1a4f9e8126..e7a5bb4fd1 100644 --- a/versioned_docs/version-6.0/indexes/boosting.mdx +++ b/versioned_docs/version-6.0/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/_boosting-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_boosting-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_boosting-java.mdx b/versioned_docs/version-6.0/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_boosting-java.mdx rename to versioned_docs/version-6.0/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_boosting-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_boosting-php.mdx b/versioned_docs/version-6.0/indexes/content/_boosting-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_boosting-php.mdx rename to versioned_docs/version-6.0/indexes/content/_boosting-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-6.0/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-6.0/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_extending-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-basics-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-metadata-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-metadata-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-metadata-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-metadata-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-metadata-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-metadata-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-metadata-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-metadata-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-metadata-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-metadata-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-metadata-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-metadata-php.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-metadata-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-metadata-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-metadata-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-metadata-python.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-metadata-python.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.0/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.0/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-spatial-data-php.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-spatial-data-php.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_indexing-spatial-data-python.mdx b/versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_indexing-spatial-data-python.mdx rename to versioned_docs/version-6.0/indexes/content/_indexing-spatial-data-python.mdx diff --git a/versioned_docs/version-6.0/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-indexes-php.mdx b/versioned_docs/version-6.0/indexes/content/_map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-indexes-php.mdx rename to versioned_docs/version-6.0/indexes/content/_map-indexes-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-indexes-python.mdx b/versioned_docs/version-6.0/indexes/content/_map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-indexes-python.mdx rename to versioned_docs/version-6.0/indexes/content/_map-indexes-python.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-reduce-indexes-php.mdx b/versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-reduce-indexes-php.mdx rename to versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_map-reduce-indexes-python.mdx b/versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_map-reduce-indexes-python.mdx rename to versioned_docs/version-6.0/indexes/content/_map-reduce-indexes-python.mdx diff --git a/versioned_docs/version-6.0/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_multi-map-indexes-php.mdx b/versioned_docs/version-6.0/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_multi-map-indexes-php.mdx rename to versioned_docs/version-6.0/indexes/content/_multi-map-indexes-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_multi-map-indexes-python.mdx b/versioned_docs/version-6.0/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_multi-map-indexes-python.mdx rename to versioned_docs/version-6.0/indexes/content/_multi-map-indexes-python.mdx diff --git a/versioned_docs/version-6.0/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-6.0/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-6.0/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_stale-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-6.0/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_storing-data-in-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_storing-data-in-index-csharp.mdx rename to versioned_docs/version-6.0/indexes/content/_storing-data-in-index-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-6.0/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-6.0/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/_storing-data-in-index-php.mdx b/versioned_docs/version-6.0/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_storing-data-in-index-php.mdx rename to versioned_docs/version-6.0/indexes/content/_storing-data-in-index-php.mdx diff --git a/versioned_docs/version-6.0/indexes/_storing-data-in-index-python.mdx b/versioned_docs/version-6.0/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_storing-data-in-index-python.mdx rename to versioned_docs/version-6.0/indexes/content/_storing-data-in-index-python.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_using-analyzers-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_using-analyzers-csharp.mdx new file mode 100644 index 0000000000..ee633b3da5 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-analyzers-csharp.mdx @@ -0,0 +1,691 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + + 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + + 2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + use the `Analyzers.Add()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`// The index definition +public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string[] Tags { get; set; } + public string Content { get; set; } + } + + public BlogPosts_ByTagsAndContent() + { + Map = posts => from post in posts + select new IndexEntry() + { + Tags = post.Tags, + Content = post.Content + }; + + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + Analyzers.Add(x => x.Content, + typeof(SnowballAnalyzer).AssemblyQualifiedName); + } +} +`} + + + + +{`// The index definition +var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") +{ + Map = posts => from post in posts + select new {post.Tags, post.Content}, + + Analyzers = + { + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + {x => x.Tags, "SimpleAnalyzer"}, + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} + } +}.ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `FieldIndexing.Exact` + * `FieldIndexing.Search` + * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`public class BlogPosts_ByContent : AbstractIndexCreationTask +\{ + public BlogPosts_ByContent() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Search' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.Search); + + // => Index-field 'Content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `FieldIndexing.Exact`, + RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask +\{ + public Employees_ByFirstAndLastName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName, + FirstName = employee.FirstName + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Exact' on index-field 'FirstName' + Indexes.Add(x => x.FirstName, FieldIndexing.Exact); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstName : AbstractIndexCreationTask +\{ + public Employees_ByFirstName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName + \}; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`public class BlogPosts_ByTitle : AbstractIndexCreationTask +\{ + public BlogPosts_ByTitle() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.No' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.No); + + // Set 'FieldStorage.Yes' to store the original content of field 'Content' + // in the index + Stores.Add(x => x.Content, FieldStorage.Yes); + + // => No analyzer will process field 'Content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public class AnalyzerDefinition +\{ + // Name of the analyzer + public string Name \{ get; set; \} + + // C# source-code of the analyzer + public string Code \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`// Define the put analyzer operation: +var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition +\{ + // The name must be same as the analyzer's class name + Name = "MyAnalyzer", + + Code = @" + using System.IO; + using Lucene.Net.Analysis; + using Lucene.Net.Analysis.Standard; + + namespace MyAnalyzer + \{ + public class MyAnalyzer : Lucene.Net.Analysis.Analyzer + \{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + throw new CodeOmitted(); + \} + \} + \}" +\}); + +// Deploy the analyzer: +store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-6.0/indexes/_using-analyzers-java.mdx b/versioned_docs/version-6.0/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-6.0/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_using-analyzers-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_using-analyzers-nodejs.mdx new file mode 100644 index 0000000000..6d96e400e2 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-analyzers-nodejs.mdx @@ -0,0 +1,655 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + +1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + +2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + set the `analyze()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content + })\`; + + // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer + this.analyze("tags", "SimpleAnalyzer"); + + // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer + this.analyze("content", "Raven.Sample.SnowballAnalyzer"); + } +} +`} + + + + +{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); +builder.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content +})\`; +builder.analyzersStrings["tags"] = "SimpleAnalyzer"; +builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; + +await store.maintenance + .send(new PutIndexesOperation( + builder.toIndexDefinition(store.conventions))); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `Exact` + * `Search` + * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Search' on index-field 'content' + this.index("content", "Search"); + + // => Index-field 'content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FirstName = employee.FirstName " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Exact' on index-field 'FirstName' + this.index("FirstName", "Exact"); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName" + + "\})"; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'No' on index-field 'content' + this.index("content", "No"); + + // Set 'Yes' to store the original content of field 'content' in the index + this.store("content", "Yes"); + + // => No analyzer will process field 'content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`const analyzerDefinition = \{ + name: "analyzerName", + code: "code" +\}; +`} + + + +| Parameter | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`const analyzerDefinition = \{ + name: "MyAnalyzer", + code: "using System.IO;\\n" + + "using Lucene.Net.Analysis;\\n" + + "using Lucene.Net.Analysis.Standard;\\n" + + "\\n" + + "namespace MyAnalyzer\\n" + + "\{\\n" + + " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + + " \{\\n" + + " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + + " \{\\n" + + " throw new CodeOmitted();\\n" + + " \}\\n" + + " \}\\n" + + "\}\\n" +\}; + +await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..46cd88508f --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..b575a1a3c0 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,488 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..27331b68cb --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,564 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`false` - will set `FieldStorage.No` (default value) +`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`null` - `FieldIndexing.Default` (default value) +`false` - `FieldIndexing.Exact` +`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-php.mdx b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..c5eafe9c00 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,568 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | | | +|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`False` - will set `FieldStorage.NO` (default value) +`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`None` - `FieldIndexing.Default` (default value) +`False` - `FieldIndexing.Exact` +`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-python.mdx b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..79953eb237 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,520 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | | | +|--------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field +The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx) + +`False` - will set `FieldStorage.NO` (default value) +`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx) + +`None` - `FieldIndexing.Default` (default value) +`False` - `FieldIndexing.Exact` +`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_using-term-vectors-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/versioned_docs/version-6.0/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-6.0/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-6.0/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-6.0/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-6.0/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/content/_what-are-indexes-csharp.mdx b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..947039be10 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_what-are-indexes-java.mdx b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..8c5adfb5e7 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_what-are-indexes-nodejs.mdx b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_what-are-indexes-php.mdx b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.0/indexes/content/_what-are-indexes-python.mdx b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/versioned_docs/version-6.0/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.0/indexes/creating-and-deploying.mdx b/versioned_docs/version-6.0/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/versioned_docs/version-6.0/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-6.0/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/extending-indexes.mdx b/versioned_docs/version-6.0/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-6.0/indexes/extending-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-basics.mdx b/versioned_docs/version-6.0/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-6.0/indexes/indexing-basics.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-6.0/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-6.0/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-6.0/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/versioned_docs/version-6.0/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-6.0/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-6.0/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-metadata.mdx b/versioned_docs/version-6.0/indexes/indexing-metadata.mdx index 6c81cc4ad3..9af5ee1d1d 100644 --- a/versioned_docs/version-6.0/indexes/indexing-metadata.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingMetadataCsharp from './_indexing-metadata-csharp.mdx'; -import IndexingMetadataJava from './_indexing-metadata-java.mdx'; -import IndexingMetadataPython from './_indexing-metadata-python.mdx'; -import IndexingMetadataPhp from './_indexing-metadata-php.mdx'; -import IndexingMetadataNodejs from './_indexing-metadata-nodejs.mdx'; +import IndexingMetadataCsharp from './content/_indexing-metadata-csharp.mdx'; +import IndexingMetadataJava from './content/_indexing-metadata-java.mdx'; +import IndexingMetadataPython from './content/_indexing-metadata-python.mdx'; +import IndexingMetadataPhp from './content/_indexing-metadata-php.mdx'; +import IndexingMetadataNodejs from './content/_indexing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-nested-data.mdx b/versioned_docs/version-6.0/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/versioned_docs/version-6.0/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-6.0/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/versioned_docs/version-6.0/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-related-documents.mdx b/versioned_docs/version-6.0/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/versioned_docs/version-6.0/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/indexing-spatial-data.mdx b/versioned_docs/version-6.0/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/versioned_docs/version-6.0/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-6.0/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/javascript-indexes.mdx b/versioned_docs/version-6.0/indexes/javascript-indexes.mdx index c3823fd587..d5a516c218 100644 --- a/versioned_docs/version-6.0/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-6.0/indexes/map-indexes.mdx b/versioned_docs/version-6.0/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/versioned_docs/version-6.0/indexes/map-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/map-reduce-indexes.mdx b/versioned_docs/version-6.0/indexes/map-reduce-indexes.mdx index b783b56532..eb29118146 100644 --- a/versioned_docs/version-6.0/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/multi-map-indexes.mdx b/versioned_docs/version-6.0/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/versioned_docs/version-6.0/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/number-type-conversion.mdx b/versioned_docs/version-6.0/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-6.0/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-6.0/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21157296fd..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1052 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-6.0/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-6.0/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_faceted-search-php.mdx b/versioned_docs/version-6.0/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_faceted-search-python.mdx b/versioned_docs/version-6.0/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 7bba94c71c..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,783 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_paging-java.mdx b/versioned_docs/version-6.0/indexes/querying/_paging-java.mdx deleted file mode 100644 index c69b33f0d7..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,307 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 253f2a5e98..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance -**Better performance**: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -**Performance hints**: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_paging-php.mdx b/versioned_docs/version-6.0/indexes/querying/_paging-php.mdx deleted file mode 100644 index 596a8e12fd..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,688 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_paging-python.mdx b/versioned_docs/version-6.0/indexes/querying/_paging-python.mdx deleted file mode 100644 index 3ca064b801..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,431 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_spatial-java.mdx b/versioned_docs/version-6.0/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_suggestions-php.mdx b/versioned_docs/version-6.0/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_suggestions-python.mdx b/versioned_docs/version-6.0/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/versioned_docs/version-6.0/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.0/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_distinct-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_exploration-queries-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_exploration-queries-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_exploration-queries-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_exploration-queries-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_exploration-queries-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_exploration-queries-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_exploration-queries-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..7adddea4b9 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1052 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_filtering-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_filtering-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_filtering-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_filtering-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_filtering-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_highlighting-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_highlighting-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_highlighting-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_highlighting-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_highlighting-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_highlighting-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_include-explanations-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_include-explanations-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_include-explanations-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_include-explanations-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_intersection-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_intersection-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_intersection-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_intersection-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_intersection-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_intersection-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_intersection-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_morelikethis-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_morelikethis-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_morelikethis-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_morelikethis-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_morelikethis-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_morelikethis-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..8f8b1df9c8 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,783 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..0e9fbc3606 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,307 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..8f97f74d19 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance +**Better performance**: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +**Performance hints**: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_paging-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..9a3a910996 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,688 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_paging-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..a357c96094 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,431 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_projections-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_projections-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_projections-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_projections-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_projections-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_projections-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_projections-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_projections-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_projections-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_projections-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_query-index-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_query-index-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_query-index-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_query-index-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_query-index-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_query-index-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_query-index-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_searching-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_searching-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_searching-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_searching-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_searching-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_searching-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_searching-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_searching-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_searching-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_searching-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_sorting-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_sorting-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_sorting-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_sorting-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_sorting-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_sorting-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_sorting-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-6.0/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_spatial-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_spatial-php.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_spatial-php.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/_spatial-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_spatial-python.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_spatial-python.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-6.0/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-6.0/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-6.0/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_suggestions-php.mdx b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/content/_suggestions-python.mdx b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/versioned_docs/version-6.0/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.0/indexes/querying/distinct.mdx b/versioned_docs/version-6.0/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-6.0/indexes/querying/distinct.mdx +++ b/versioned_docs/version-6.0/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/exploration-queries.mdx b/versioned_docs/version-6.0/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/versioned_docs/version-6.0/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-6.0/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/faceted-search.mdx b/versioned_docs/version-6.0/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/versioned_docs/version-6.0/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-6.0/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/filtering.mdx b/versioned_docs/version-6.0/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/versioned_docs/version-6.0/indexes/querying/filtering.mdx +++ b/versioned_docs/version-6.0/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/highlighting.mdx b/versioned_docs/version-6.0/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/versioned_docs/version-6.0/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-6.0/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/include-explanations.mdx b/versioned_docs/version-6.0/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/versioned_docs/version-6.0/indexes/querying/include-explanations.mdx +++ b/versioned_docs/version-6.0/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/intersection.mdx b/versioned_docs/version-6.0/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/versioned_docs/version-6.0/indexes/querying/intersection.mdx +++ b/versioned_docs/version-6.0/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/morelikethis.mdx b/versioned_docs/version-6.0/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/versioned_docs/version-6.0/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-6.0/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/paging.mdx b/versioned_docs/version-6.0/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/versioned_docs/version-6.0/indexes/querying/paging.mdx +++ b/versioned_docs/version-6.0/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/projections.mdx b/versioned_docs/version-6.0/indexes/querying/projections.mdx index 6a24194fc0..779a07b48b 100644 --- a/versioned_docs/version-6.0/indexes/querying/projections.mdx +++ b/versioned_docs/version-6.0/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/query-index.mdx b/versioned_docs/version-6.0/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/versioned_docs/version-6.0/indexes/querying/query-index.mdx +++ b/versioned_docs/version-6.0/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/searching.mdx b/versioned_docs/version-6.0/indexes/querying/searching.mdx index 9f0b5aebc1..9b88c79e82 100644 --- a/versioned_docs/version-6.0/indexes/querying/searching.mdx +++ b/versioned_docs/version-6.0/indexes/querying/searching.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/sorting.mdx b/versioned_docs/version-6.0/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/versioned_docs/version-6.0/indexes/querying/sorting.mdx +++ b/versioned_docs/version-6.0/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/spatial.mdx b/versioned_docs/version-6.0/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/versioned_docs/version-6.0/indexes/querying/spatial.mdx +++ b/versioned_docs/version-6.0/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-6.0/indexes/querying/suggestions.mdx b/versioned_docs/version-6.0/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/versioned_docs/version-6.0/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-6.0/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/sorting-and-collation.mdx b/versioned_docs/version-6.0/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-6.0/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-6.0/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-6.0/indexes/stale-indexes.mdx b/versioned_docs/version-6.0/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-6.0/indexes/stale-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/storing-data-in-index.mdx b/versioned_docs/version-6.0/indexes/storing-data-in-index.mdx index d353ecb33e..3f3fe9512c 100644 --- a/versioned_docs/version-6.0/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-6.0/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/using-analyzers.mdx b/versioned_docs/version-6.0/indexes/using-analyzers.mdx index ff0865eb70..cfaf304f2e 100644 --- a/versioned_docs/version-6.0/indexes/using-analyzers.mdx +++ b/versioned_docs/version-6.0/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/using-dynamic-fields.mdx b/versioned_docs/version-6.0/indexes/using-dynamic-fields.mdx index 010c89de9b..fe92642e46 100644 --- a/versioned_docs/version-6.0/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-6.0/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/indexes/using-term-vectors.mdx b/versioned_docs/version-6.0/indexes/using-term-vectors.mdx index 94ef7ada0b..819e006fd0 100644 --- a/versioned_docs/version-6.0/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-6.0/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/versioned_docs/version-6.0/indexes/what-are-indexes.mdx b/versioned_docs/version-6.0/indexes/what-are-indexes.mdx index b05d8422dc..8821d797d4 100644 --- a/versioned_docs/version-6.0/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-6.0/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/server/_embedded-csharp.mdx b/versioned_docs/version-6.0/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/server/_embedded-csharp.mdx rename to versioned_docs/version-6.0/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-6.0/server/_embedded-java.mdx b/versioned_docs/version-6.0/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-6.0/server/_embedded-java.mdx rename to versioned_docs/version-6.0/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-6.0/server/embedded.mdx b/versioned_docs/version-6.0/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/versioned_docs/version-6.0/server/embedded.mdx +++ b/versioned_docs/version-6.0/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-6.0/server/extensions/_refresh-csharp.mdx b/versioned_docs/version-6.0/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/versioned_docs/version-6.0/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-6.0/server/extensions/_refresh-nodejs.mdx b/versioned_docs/version-6.0/server/extensions/_refresh-nodejs.mdx deleted file mode 100644 index f8a0a3d28c..0000000000 --- a/versioned_docs/version-6.0/server/extensions/_refresh-nodejs.mdx +++ /dev/null @@ -1,137 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - -## Overview - -To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. -This indicates when the document should be refreshed. - -This will cause the document to refresh **_only once_**! The refresh operation removes -the `@refresh` flag. - -The exact time that the document refreshes is not determined by the value of `@refresh` -- rather, the server refreshes documents at regular intervals determined by the Refresh -Configuration. The default interval is 60 seconds. - -Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) -to increment the same way it would after any other kind of update to the document. -This triggers any features that react to documents updating, including but not limited -to: - -* The document is re-indexed by any indexes that cover it. -* [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. -* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. - - - -## Examples - -#### Setting the refresh configuration for a database: - -To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. - - - -{`// Enable document refreshing and set the refresh interval to 5 minutes: -// ===================================================================== - -// Define the refresh configuration object -const refreshConfiguration = \{ - disabled: false, // Enable refreshing - refreshFrequencyInSec: 300 // Set interval to 5 minutes -\}; - -// Define the configure refresh operation, pass the configuration to set -const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); - -// Execute the operation by passing it to maintenance.send -await documentStore.maintenance.send(configureRefreshOp); -`} - - -#### Set a document to refresh 1 hour from now: - - - -{`// Setting a document to refresh after 1 hour: -// ==========================================+ - -// Load a document -const session = documentStore.openSession(); -const employee = await session.load("employees/1-A"); - -// Get the metadata of the document -const metadata = session.advanced.getMetadataFor(employee); - -// Set the "@refresh" metadata property with the refresh date in UTC format -const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) -metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); - -// Save the document -await session.saveChanges(); -`} - - - - - -## Syntax - - - -{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); -`} - - - -[//]: # (| Parameter | Type | Description |) -[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) -[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) -[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) -[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) - - - -{`// The refreshConfiguration object -\{ - disabled, - refreshFrequencyInSec -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| -| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | -| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-6.0/server/extensions/_expiration-csharp.mdx b/versioned_docs/version-6.0/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/server/extensions/_expiration-csharp.mdx rename to versioned_docs/version-6.0/server/extensions/content/_expiration-csharp.mdx diff --git a/versioned_docs/version-6.0/server/extensions/_expiration-nodejs.mdx b/versioned_docs/version-6.0/server/extensions/content/_expiration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/server/extensions/_expiration-nodejs.mdx rename to versioned_docs/version-6.0/server/extensions/content/_expiration-nodejs.mdx diff --git a/versioned_docs/version-6.0/server/extensions/content/_refresh-csharp.mdx b/versioned_docs/version-6.0/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/versioned_docs/version-6.0/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-6.0/server/extensions/content/_refresh-nodejs.mdx b/versioned_docs/version-6.0/server/extensions/content/_refresh-nodejs.mdx new file mode 100644 index 0000000000..a4e68e0f7e --- /dev/null +++ b/versioned_docs/version-6.0/server/extensions/content/_refresh-nodejs.mdx @@ -0,0 +1,137 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + +## Overview + +To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. +This indicates when the document should be refreshed. + +This will cause the document to refresh **_only once_**! The refresh operation removes +the `@refresh` flag. + +The exact time that the document refreshes is not determined by the value of `@refresh` +- rather, the server refreshes documents at regular intervals determined by the Refresh +Configuration. The default interval is 60 seconds. + +Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) +to increment the same way it would after any other kind of update to the document. +This triggers any features that react to documents updating, including but not limited +to: + +* The document is re-indexed by any indexes that cover it. +* [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. +* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. + + + +## Examples + +#### Setting the refresh configuration for a database: + +To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. + + + +{`// Enable document refreshing and set the refresh interval to 5 minutes: +// ===================================================================== + +// Define the refresh configuration object +const refreshConfiguration = \{ + disabled: false, // Enable refreshing + refreshFrequencyInSec: 300 // Set interval to 5 minutes +\}; + +// Define the configure refresh operation, pass the configuration to set +const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); + +// Execute the operation by passing it to maintenance.send +await documentStore.maintenance.send(configureRefreshOp); +`} + + +#### Set a document to refresh 1 hour from now: + + + +{`// Setting a document to refresh after 1 hour: +// ==========================================+ + +// Load a document +const session = documentStore.openSession(); +const employee = await session.load("employees/1-A"); + +// Get the metadata of the document +const metadata = session.advanced.getMetadataFor(employee); + +// Set the "@refresh" metadata property with the refresh date in UTC format +const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) +metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); + +// Save the document +await session.saveChanges(); +`} + + + + + +## Syntax + + + +{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); +`} + + + +[//]: # (| Parameter | Type | Description |) +[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) +[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) +[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) +[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) + + + +{`// The refreshConfiguration object +\{ + disabled, + refreshFrequencyInSec +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| +| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | +| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-6.0/server/extensions/expiration.mdx b/versioned_docs/version-6.0/server/extensions/expiration.mdx index 3986525bb8..791e4136d6 100644 --- a/versioned_docs/version-6.0/server/extensions/expiration.mdx +++ b/versioned_docs/version-6.0/server/extensions/expiration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; -import ExpirationNodejs from './_expiration-nodejs.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; +import ExpirationNodejs from './content/_expiration-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/server/extensions/refresh.mdx b/versioned_docs/version-6.0/server/extensions/refresh.mdx index 8820271cfb..08eefe0c4f 100644 --- a/versioned_docs/version-6.0/server/extensions/refresh.mdx +++ b/versioned_docs/version-6.0/server/extensions/refresh.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; -import RefreshNodejs from './_refresh-nodejs.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; +import RefreshNodejs from './content/_refresh-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-6.0/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-6.0/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-6.0/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-6.0/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.0/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-6.0/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-6.0/server/storage/documents-compression.mdx b/versioned_docs/version-6.0/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-6.0/server/storage/documents-compression.mdx +++ b/versioned_docs/version-6.0/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/start/_test-driver-csharp.mdx b/versioned_docs/version-6.0/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-6.0/start/_test-driver-csharp.mdx rename to versioned_docs/version-6.0/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-6.0/start/_test-driver-java.mdx b/versioned_docs/version-6.0/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-6.0/start/_test-driver-java.mdx rename to versioned_docs/version-6.0/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-csharp.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-nodejs.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/versioned_docs/version-6.0/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/_overview-csharp.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/versioned_docs/version-6.0/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/_overview-nodejs.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index d2f9cd8940..0000000000 --- a/versioned_docs/version-6.0/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../..//client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-csharp.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/versioned_docs/version-6.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-csharp.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-nodejs.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..dee2af2555 --- /dev/null +++ b/versioned_docs/version-6.0/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../..//client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/existing-project.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/versioned_docs/version-6.0/start/guides/azure-functions/existing-project.mdx +++ b/versioned_docs/version-6.0/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/start/guides/azure-functions/overview.mdx b/versioned_docs/version-6.0/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/versioned_docs/version-6.0/start/guides/azure-functions/overview.mdx +++ b/versioned_docs/version-6.0/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.0/start/test-driver.mdx b/versioned_docs/version-6.0/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/versioned_docs/version-6.0/start/test-driver.mdx +++ b/versioned_docs/version-6.0/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-6.2/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-6.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-6.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-6.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-6.2/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-6.2/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-6.2/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-6.2/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-6.2/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-6.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-6.2/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-6.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-6.2/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-6.2/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-6.2/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-6.2/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-6.2/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-6.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-6.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-6.2/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx b/versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx rename to versioned_docs/version-6.2/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 668d999b7d..5c6923b919 100644 --- a/versioned_docs/version-6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchNodejs from './_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchNodejs from './content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/commands/_overview-csharp.mdx b/versioned_docs/version-6.2/client-api/commands/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/_overview-csharp.mdx rename to versioned_docs/version-6.2/client-api/commands/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/_overview-java.mdx b/versioned_docs/version-6.2/client-api/commands/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/_overview-java.mdx rename to versioned_docs/version-6.2/client-api/commands/content/_overview-java.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/_overview-nodejs.mdx b/versioned_docs/version-6.2/client-api/commands/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/_overview-nodejs.mdx rename to versioned_docs/version-6.2/client-api/commands/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_delete-nodejs.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_delete-nodejs.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_delete-php.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_delete-php.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_delete-php.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_delete-python.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_delete-python.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_delete-python.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_get-php.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_get-php.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_get-php.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_get-python.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_get-python.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_get-python.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_put-nodejs.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_put-nodejs.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_put-php.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_put-php.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_put-php.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/_put-python.mdx b/versioned_docs/version-6.2/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/commands/documents/_put-python.mdx rename to versioned_docs/version-6.2/client-api/commands/documents/content/_put-python.mdx diff --git a/versioned_docs/version-6.2/client-api/commands/documents/delete.mdx b/versioned_docs/version-6.2/client-api/commands/documents/delete.mdx index 61091b815c..a88bb5f5db 100644 --- a/versioned_docs/version-6.2/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-6.2/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/commands/documents/get.mdx b/versioned_docs/version-6.2/client-api/commands/documents/get.mdx index 1e303a3f73..325076a4dc 100644 --- a/versioned_docs/version-6.2/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-6.2/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/commands/documents/put.mdx b/versioned_docs/version-6.2/client-api/commands/documents/put.mdx index ee9e70143c..9c8ba28480 100644 --- a/versioned_docs/version-6.2/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-6.2/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/commands/overview.mdx b/versioned_docs/version-6.2/client-api/commands/overview.mdx index dd0aca1a6c..744fb40071 100644 --- a/versioned_docs/version-6.2/client-api/commands/overview.mdx +++ b/versioned_docs/version-6.2/client-api/commands/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-6.2/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/conventions.mdx b/versioned_docs/version-6.2/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/versioned_docs/version-6.2/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/deserialization.mdx b/versioned_docs/version-6.2/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-6.2/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-6.2/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-6.2/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to versioned_docs/version-6.2/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/versioned_docs/version-6.2/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-6.2/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/versioned_docs/version-6.2/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/configuration/serialization.mdx b/versioned_docs/version-6.2/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-6.2/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-6.2/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-6.2/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/_creating-document-store-java.mdx b/versioned_docs/version-6.2/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-6.2/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-6.2/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-6.2/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-6.2/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-6.2/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-6.2/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-6.2/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-6.2/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-6.2/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-6.2/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-6.2/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/creating-document-store.mdx b/versioned_docs/version-6.2/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-6.2/client-api/creating-document-store.mdx +++ b/versioned_docs/version-6.2/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index cd09e4587d..0000000000 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index c2d1857b87..0000000000 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,134 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 12e6eedbd2..0000000000 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/concurrent-subscriptions.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_examples-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..30fd3f7254 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..aaa26a16f7 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,134 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..d82e45f68c --- /dev/null +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_examples-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to versioned_docs/version-6.2/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-6.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 881ea78195..16791e745a 100644 --- a/versioned_docs/version-6.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-6.2/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-6.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-6.2/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-6.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-6.2/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-6.2/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-6.2/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-6.2/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-6.2/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-6.2/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-6.2/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-nodejs.mdx b/versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to versioned_docs/version-6.2/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-6.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-6.2/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-6.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-6.2/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-6.2/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-6.2/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/versioned_docs/version-6.2/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-6.2/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-6.2/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-6.2/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-6.2/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/net-client-versions.mdx b/versioned_docs/version-6.2/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-6.2/client-api/net-client-versions.mdx +++ b/versioned_docs/version-6.2/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_delete-attachment-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_get-attachment-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_get-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/attachments/_put-attachment-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/attachments/content/_put-attachment-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/delete-attachment.mdx index b1b8dc0862..b4a5d42046 100644 --- a/versioned_docs/version-6.2/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-6.2/client-api/operations/attachments/delete-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; -import DeleteAttachmentNodejs from './_delete-attachment-nodejs.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; +import DeleteAttachmentNodejs from './content/_delete-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/get-attachment.mdx index dfbe7f67bf..16af9d26fc 100644 --- a/versioned_docs/version-6.2/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-6.2/client-api/operations/attachments/get-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; -import GetAttachmentNodejs from './_get-attachment-nodejs.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; +import GetAttachmentNodejs from './content/_get-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-6.2/client-api/operations/attachments/put-attachment.mdx index 7d63f1af0f..19a6aa8702 100644 --- a/versioned_docs/version-6.2/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-6.2/client-api/operations/attachments/put-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; -import PutAttachmentNodejs from './_put-attachment-nodejs.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; +import PutAttachmentNodejs from './content/_put-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-php.mdx b/versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-php.mdx rename to versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-python.mdx b/versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/common/_delete-by-query-python.mdx rename to versioned_docs/version-6.2/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-6.2/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/versioned_docs/version-6.2/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-6.2/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-php.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-php.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-python.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_overview-python.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_overview-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 5cd2b2f3bb..4dbcb13cc5 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; -import DeleteCompareExchangeValueNodejs from './_delete-compare-exchange-value-nodejs.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueNodejs from './content/_delete-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 5a3faf4c6d..797adb1e32 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; -import GetCompareExchangeValueNodejs from './_get-compare-exchange-value-nodejs.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueNodejs from './content/_get-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index 3cd524682d..7371593482 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; -import GetCompareExchangeValuesNodejs from './_get-compare-exchange-values-nodejs.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesNodejs from './content/_get-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/include-compare-exchange.mdx index ef602a655c..c2da54868f 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; -import IncludeCompareExchangeNodejs from './_include-compare-exchange-nodejs.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeNodejs from './content/_include-compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/overview.mdx index 66ee3a1273..d63e1a098c 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "php"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-6.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index ed5ae625f9..fe51a43af8 100644 --- a/versioned_docs/version-6.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-6.2/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; -import PutCompareExchangeValueNodejs from './_put-compare-exchange-value-nodejs.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueNodejs from './content/_put-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/_what-are-operations-php.mdx b/versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/_what-are-operations-php.mdx rename to versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/_what-are-operations-python.mdx b/versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/_what-are-operations-python.mdx rename to versioned_docs/version-6.2/client-api/operations/content/_what-are-operations-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-php.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_counter-batch-php.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_get-counters-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_get-counters-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/_get-counters-php.mdx b/versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/counters/_get-counters-php.mdx rename to versioned_docs/version-6.2/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-6.2/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/versioned_docs/version-6.2/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-6.2/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-6.2/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/versioned_docs/version-6.2/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-6.2/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to versioned_docs/version-6.2/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-6.2/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index 411e7a0097..0de1650d28 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 0c2b4eac5d..375985d7be 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 097f3eefc1..170c2de116 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/_get-stats-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/add-etl.mdx index e1ee997ddf..f4df4215da 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx index c7bbd9c2d5..0088f23bbf 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx index ecbdd10352..619c94b24d 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OngoingTaskOperationsCsharp from './_ongoing-task-operations-csharp.mdx'; +import OngoingTaskOperationsCsharp from './content/_ongoing-task-operations-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_set-based-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_set-based-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/_single-document-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/patching/_single-document-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/patching/set-based.mdx b/versioned_docs/version-6.2/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/versioned_docs/version-6.2/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-6.2/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/patching/single-document.mdx b/versioned_docs/version-6.2/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/versioned_docs/version-6.2/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-6.2/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-php.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-php.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-python.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_add-database-node-python.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-php.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-php.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-python.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_compact-database-python.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/create-database.mdx index 06626431e0..59effdb582 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 701e1d1092..7763f566c3 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 8730f44929..5698a164ad 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-6.2/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/operations/what-are-operations.mdx b/versioned_docs/version-6.2/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/versioned_docs/version-6.2/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-6.2/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-6.2/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-6.2/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/security/deserialization-security.mdx b/versioned_docs/version-6.2/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-6.2/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-6.2/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index 811678c09d..0000000000 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - session.Store(new User(), "users/johndoe"); - session.SaveChanges(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var session1 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var session2 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = session1.Load("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = session2.Load("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - session1.SaveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - session2.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - await asyncSession.SaveChangesAsync(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var asyncSession1 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var asyncSession2 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // asyncSession1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - await asyncSession1.SaveChangesAsync(); - - // asyncSession2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - await asyncSession2.SaveChangesAsync(); -} -`} - - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - session.Store(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`Load` the document into the session before storing it** - - even if the document is expected to be new. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating a new one or modifying if already exists - var user = session.Load("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - session.Store(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating or updating - var user = await asyncSession.LoadAsync("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - await asyncSession.StoreAsync(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index d9ae1ff263..0000000000 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,261 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session: -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two concurrent cluster-wide sessions: -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// Both sessions load the same document: -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 saves its changes first — -// this increments the Raft index of the associated atomic guard. -await session1.saveChanges(); - -// session2 tries to save using an outdated atomic guard version -// and fails with a ConcurrencyException. -await session2.saveChanges(); -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`const session = documentStore.openSession(\{ - // Open a cluster-wide session - transactionMode: "ClusterWide" -\}); - -// Load the user document BEFORE creating or updating -const user = await session.load("users/johndoe"); - -if (!user) \{ - // Document doesn't exist => create a new document - const newUser = \{ - name: "John Doe", - // ... initialize other properties - \}; - - // Store the new user document in the session - await session.store(newUser, "users/johndoe"); - -\} else \{ - // Document exists => apply your modifications - user.name = "New name"; - // ... make any other updates - - // No need to call store() again - // RavenDB tracks changes on loaded entities -\} - -// Commit your changes -await session.saveChanges(); -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-php.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-php.mdx deleted file mode 100644 index aee89e6ab0..0000000000 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-php.mdx +++ /dev/null @@ -1,276 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`// Open a cluster-wide session: -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // An atomic-guard is now automatically created for the new document "users/johndoe". - $session->saveChanges(); -\} finally \{ - $session->close(); -\} - -// Open two concurrent cluster-wide sessions: - -$sessionOptions1 = new SessionOptions(); -$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); - -$session1 = $store->openSession($sessionOptions1); -try \{ - $sessionOptions2 = new SessionOptions(); - $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); - $session2 = $store->openSession($sessionOptions2); - - try \{ - // Both sessions load the same document: - var $loadedUser1 = $session1->load(User::class, "users/johndoe"); - $loadedUser1->setName("jindoe"); - - $loadedUser2 = $session2->load(User::class, "users/johndoe"); - $loadedUser2->setName("jandoe"); - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - $session1->saveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - $session2->saveChanges(); - \} finally \{ - $session2->close(); - \} - -\} finally \{ - $session1->close(); -\} -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); -$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // No atomic-guard will be created upon saveChanges - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`// Open a cluster-wide session -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); -try \{ - // Load the user document BEFORE creating or updating - $user = $session->load(User::class, "users/johndoe"); - - if ($user === null) \{ - // Document doesn't exist => create a new document: - $newUser = new User(); - $newUser->setName("John Doe"); - // ... initialize other properties - - // Store the new user document in the session - $session->store($newUser, "users/johndoe"); - \} else \{ - // Document exists => apply your modifications: - $user->setName("New name"); - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - \} - - // Commit your changes - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-python.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-python.mdx deleted file mode 100644 index e650aac9bf..0000000000 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_atomic-guards-python.mdx +++ /dev/null @@ -1,251 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`with store.open_session( - # Open a cluster-wide session: - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session: - session.store(User(), "users/johndoe") - session.save_changes() - # An atomic-guard is now automatically created for the new document "users/johndoe" - -# Open two concurrent cluster-wide sessions: -with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session1: - with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) - ) as session2: - # Both sessions load the same document: - loaded_user_1 = session1.load("users/johndoe", User) - loaded_user_1.name = "jindoe" - loaded_user_2 = session2.load("users/johndoe", User) - loaded_user_2.name = "jandoe" - - # session1 saves its changes first — - # this increments the Raft index of the associated atomic guard. - session1.save_changes() - - # session2 tries to save using an outdated atomic guard version - # and fails with a ConcurrencyException. - session2.save_changes() -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`with store.open_session( - # Open a cluster-wide session - session_options=SessionOptions( - transaction_mode=TransactionMode.CLUSTER_WIDE, - disable_atomic_document_writes_in_cluster_wide_transaction=True, - ) -) as session: - session.store(User(), "users/johndoe") - - # No atomic-guard will be created upon save_changes - session.save_changes() -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`with store.open_session( - session_options=SessionOptions( - # Open a cluster-wide session - transaction_mode=TransactionMode.CLUSTER_WIDE - ) -) as session: - # Load the user document BEFORE creating or updating - user = session.load("users/johndoe", User) - - if user is None: - # Document doesn't exist => create a new document - new_user = User() - new_user.name = "John Doe" - # ... initialize other properties - - # Store the new user document in the session - session.store(new_user, "users/johndoe") - else: - # Document exists => apply your modifications - user.name = "New name" - # ... make any other updates - - # No need to call store() again - # RavenDB tracks changes on loaded entities - - # Commit your changes - session.save_changes() -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/atomic-guards.mdx index 8e705c3a32..29ace602dc 100644 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsPython from './_atomic-guards-python.mdx'; -import AtomicGuardsPhp from './_atomic-guards-php.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsPython from './content/_atomic-guards-python.mdx'; +import AtomicGuardsPhp from './content/_atomic-guards-php.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/compare-exchange.mdx index d4bdc9d5da..a98b9edf99 100644 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangePython from './_compare-exchange-python.mdx'; -import CompareExchangePhp from './_compare-exchange-php.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangePython from './content/_compare-exchange-python.mdx'; +import CompareExchangePhp from './content/_compare-exchange-php.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..9c603424ba --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + session.Store(new User(), "users/johndoe"); + session.SaveChanges(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var session1 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var session2 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = session1.Load("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = session2.Load("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + session1.SaveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + session2.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + await asyncSession.SaveChangesAsync(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var asyncSession1 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var asyncSession2 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // asyncSession1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + await asyncSession1.SaveChangesAsync(); + + // asyncSession2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + await asyncSession2.SaveChangesAsync(); +} +`} + + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + session.Store(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`Load` the document into the session before storing it** - + even if the document is expected to be new. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating a new one or modifying if already exists + var user = session.Load("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + session.Store(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating or updating + var user = await asyncSession.LoadAsync("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + await asyncSession.StoreAsync(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..2825373609 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,261 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session: +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two concurrent cluster-wide sessions: +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// Both sessions load the same document: +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 saves its changes first — +// this increments the Raft index of the associated atomic guard. +await session1.saveChanges(); + +// session2 tries to save using an outdated atomic guard version +// and fails with a ConcurrencyException. +await session2.saveChanges(); +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`const session = documentStore.openSession(\{ + // Open a cluster-wide session + transactionMode: "ClusterWide" +\}); + +// Load the user document BEFORE creating or updating +const user = await session.load("users/johndoe"); + +if (!user) \{ + // Document doesn't exist => create a new document + const newUser = \{ + name: "John Doe", + // ... initialize other properties + \}; + + // Store the new user document in the session + await session.store(newUser, "users/johndoe"); + +\} else \{ + // Document exists => apply your modifications + user.name = "New name"; + // ... make any other updates + + // No need to call store() again + // RavenDB tracks changes on loaded entities +\} + +// Commit your changes +await session.saveChanges(); +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx new file mode 100644 index 0000000000..c6fcf1e501 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx @@ -0,0 +1,276 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`// Open a cluster-wide session: +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // An atomic-guard is now automatically created for the new document "users/johndoe". + $session->saveChanges(); +\} finally \{ + $session->close(); +\} + +// Open two concurrent cluster-wide sessions: + +$sessionOptions1 = new SessionOptions(); +$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); + +$session1 = $store->openSession($sessionOptions1); +try \{ + $sessionOptions2 = new SessionOptions(); + $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); + $session2 = $store->openSession($sessionOptions2); + + try \{ + // Both sessions load the same document: + var $loadedUser1 = $session1->load(User::class, "users/johndoe"); + $loadedUser1->setName("jindoe"); + + $loadedUser2 = $session2->load(User::class, "users/johndoe"); + $loadedUser2->setName("jandoe"); + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + $session1->saveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + $session2->saveChanges(); + \} finally \{ + $session2->close(); + \} + +\} finally \{ + $session1->close(); +\} +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); +$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // No atomic-guard will be created upon saveChanges + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`// Open a cluster-wide session +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); +try \{ + // Load the user document BEFORE creating or updating + $user = $session->load(User::class, "users/johndoe"); + + if ($user === null) \{ + // Document doesn't exist => create a new document: + $newUser = new User(); + $newUser->setName("John Doe"); + // ... initialize other properties + + // Store the new user document in the session + $session->store($newUser, "users/johndoe"); + \} else \{ + // Document exists => apply your modifications: + $user->setName("New name"); + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + \} + + // Commit your changes + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx new file mode 100644 index 0000000000..489119ff63 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx @@ -0,0 +1,251 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`with store.open_session( + # Open a cluster-wide session: + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session: + session.store(User(), "users/johndoe") + session.save_changes() + # An atomic-guard is now automatically created for the new document "users/johndoe" + +# Open two concurrent cluster-wide sessions: +with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session1: + with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) + ) as session2: + # Both sessions load the same document: + loaded_user_1 = session1.load("users/johndoe", User) + loaded_user_1.name = "jindoe" + loaded_user_2 = session2.load("users/johndoe", User) + loaded_user_2.name = "jandoe" + + # session1 saves its changes first — + # this increments the Raft index of the associated atomic guard. + session1.save_changes() + + # session2 tries to save using an outdated atomic guard version + # and fails with a ConcurrencyException. + session2.save_changes() +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`with store.open_session( + # Open a cluster-wide session + session_options=SessionOptions( + transaction_mode=TransactionMode.CLUSTER_WIDE, + disable_atomic_document_writes_in_cluster_wide_transaction=True, + ) +) as session: + session.store(User(), "users/johndoe") + + # No atomic-guard will be created upon save_changes + session.save_changes() +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`with store.open_session( + session_options=SessionOptions( + # Open a cluster-wide session + transaction_mode=TransactionMode.CLUSTER_WIDE + ) +) as session: + # Load the user document BEFORE creating or updating + user = session.load("users/johndoe", User) + + if user is None: + # Document doesn't exist => create a new document + new_user = User() + new_user.name = "John Doe" + # ... initialize other properties + + # Store the new user document in the session + session.store(new_user, "users/johndoe") + else: + # Document exists => apply your modifications + user.name = "New name" + # ... make any other updates + + # No need to call store() again + # RavenDB tracks changes on loaded entities + + # Commit your changes + session.save_changes() +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-php.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-php.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-python.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_compare-exchange-python.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-php.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-php.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-python.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/cluster-transaction/_overview-python.mdx rename to versioned_docs/version-6.2/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-6.2/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/versioned_docs/version-6.2/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-6.2/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to versioned_docs/version-6.2/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/versioned_docs/version-6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_deleting-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_deleting-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_deleting-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_deleting-entities-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_deleting-entities-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_deleting-entities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_loading-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_loading-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_loading-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_loading-entities-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_loading-entities-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_loading-entities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_opening-a-session-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_opening-a-session-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_opening-a-session-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_opening-a-session-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_opening-a-session-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_opening-a-session-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_saving-changes-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_saving-changes-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_saving-changes-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_saving-changes-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_saving-changes-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_saving-changes-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_storing-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_storing-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_storing-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_storing-entities-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_storing-entities-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_storing-entities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_updating-entities-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_updating-entities-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_updating-entities-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_updating-entities-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_updating-entities-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_updating-entities-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to versioned_docs/version-6.2/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/deleting-entities.mdx b/versioned_docs/version-6.2/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/versioned_docs/version-6.2/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-6.2/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-6.2/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-6.2/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-6.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-6.2/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-document-exists-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_clear-a-session-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_defer-operations-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-current-session-node-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-counters-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-php.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-php.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-python.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_refresh-entity-python.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-6.2/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-6.2/client-api/session/how-to/evict-entity-from-a-session.mdx index 958fc3efc6..b8527408ff 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/get-tracked-entities.mdx b/versioned_docs/version-6.2/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/get-tracked-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-6.2/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-6.2/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-6.2/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-6.2/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-6.2/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-6.2/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/loading-entities.mdx b/versioned_docs/version-6.2/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/versioned_docs/version-6.2/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/opening-a-session.mdx b/versioned_docs/version-6.2/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/versioned_docs/version-6.2/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-6.2/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 76701c04da..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,962 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index f63a3d807a..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,514 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - -* Note the following difference between the underlying search engines: - - * When using __Lucene__: - This metadata property is always available in the results. - - * When using __Corax__: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index f970fa79dd..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,539 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) # todo gracjan: check if its possible to order by again without then_by - # todo reeb: skip this example for now, we'll get back to it later on - # A secondary sort can be applied -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 24a9a9d9eb..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,622 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index e9e99cf398..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -| Parameter | Type | Description | -|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-count-query-results-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-customize-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..a3f3e8abc4 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,962 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..3229d3c59f --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,514 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + +* Note the following difference between the underlying search engines: + + * When using __Lucene__: + This metadata property is always available in the results. + + * When using __Corax__: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..e127cbf432 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,539 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) # todo gracjan: check if its possible to order by again without then_by + # todo reeb: skip this example for now, we'll get back to it later on + # A secondary sort can be applied +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-project-query-results-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-intersect-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..31fe795d5e --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,622 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f0354dff46 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +| Parameter | Type | Description | +|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/_sort-query-results-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index 157fe9e4ec..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 90c08b9c95..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index 82050a7150..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -The `QueryTimings` object will be filled with the timings when the query returns. - -| `QueryTimings` | | | -|------------------|-----------------------------|---------------------------------------------------| -| __durationInMs__ | `long` | Total duration | -| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 2594955761..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,106 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 447455323e..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index a24ff39584..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..074ff4437e --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..87f6efdabe --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..dde738eb47 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +The `QueryTimings` object will be filled with the timings when the query returns. + +| `QueryTimings` | | | +|------------------|-----------------------------|---------------------------------------------------| +| __durationInMs__ | `long` | Total duration | +| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..04c49f9a7d --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,106 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..ff61a93e87 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..ed2089f0f5 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-6.2/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-project-query-results.mdx index 005a01c964..505ff9b85d 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-6.2/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/sort-query-results.mdx index 6da793c2fe..38530aba4c 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/sort-query-results.mdx @@ -9,10 +9,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 4d6da16a2d..0000000000 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,373 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) - -# todo reeb & gracjan: lets implement it after 5.4 release -# i have a perfect ticket for that -# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_full-text-search-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..0bf2fc548a --- /dev/null +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,373 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) + +# todo reeb & gracjan: lets implement it after 5.4 release +# i have a perfect ticket for that +# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_proximity-search-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-php.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-php.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-python.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/session/querying/text-search/_using-regex-python.mdx rename to versioned_docs/version-6.2/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-6.2/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/versioned_docs/version-6.2/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-6.2/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/saving-changes.mdx b/versioned_docs/version-6.2/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/versioned_docs/version-6.2/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-6.2/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/storing-entities.mdx b/versioned_docs/version-6.2/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/versioned_docs/version-6.2/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/updating-entities.mdx b/versioned_docs/version-6.2/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/versioned_docs/version-6.2/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-6.2/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-6.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/versioned_docs/version-6.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-6.2/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-6.2/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-6.2/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-6.2/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/setting-up-default-database.mdx b/versioned_docs/version-6.2/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-6.2/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-6.2/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-6.2/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-6.2/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-6.2/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-6.2/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-6.2/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/client-api/what-is-a-document-store.mdx b/versioned_docs/version-6.2/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-6.2/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-6.2/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/data-archival/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-6.2/data-archival/_archived-documents-and-other-features-csharp.mdx deleted file mode 100644 index 3a5ba1beed..0000000000 --- a/versioned_docs/version-6.2/data-archival/_archived-documents-and-other-features-csharp.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), - RavenDB features can detect these documents and handle them in different ways. - -* Some features, like indexes and data subscriptions, provide native support for configuring whether to: - * **Exclude** archived documents from processing, reducing index size and improving query relevance. - * **Include** only archived documents, for tasks that target archived data specifically. - * **Process both** archived and non-archived documents when needed. - -* Other features can manage archived documents differently based on their purpose. For example: - * ETL tasks can skip or selectively process archived documents. - * Archived documents can be included or excluded when exporting or importing data. - -* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. - -* Learn more below about how various RavenDB features interact with archived documents. -* In this article: - * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) - * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) - * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) - * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) - * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) - * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) - * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) - * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) - * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) - * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) - - -## Archived documents and indexing - -* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. -* Archiving documents and excluding them from indexing can be an effective way to maintain performance. - By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. - This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. -* **Configuring indexing behavior - Static indexes**: - * **At the database level or server-wide**: - To control whether static indexes process archived documents from the source collection, - set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) - configuration key at either the database level or server-wide (default: `ExcludeArchived`). - * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. - This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. - * **Per index**: - You can override this global behavior per-index directly in the index definition, using the Client API from the Studio - (see the examples below). - -* **Configuring indexing behavior - Auto indexes:** - * **At the database level or server-wide**: - To control whether auto-indexes process archived documents at the database level or server-wide, - set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). - * **Per index**: - Unlike static indexes, you cannot configure this behavior per auto-index, - because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the index. - * `IncludeArchived`: both archived and non-archived documents are processed by the index. - * `ArchivedOnly`: only archived documents are processed by the index. -##### Configuring archived document processing for a static index - from the Client API - -You can configure how a static index handles archived documents when creating the index using the Client API. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`public class Orders_ByOrderDate : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public DateTime OrderDate { get; set; } - } - - public Orders_ByOrderDate() - { - Map = orders => from order in orders - select new IndexEntry - { - OrderDate = order.OrderedAt - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByOrderDate_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - return { - OrderDate: order.OrderedAt - }; - })" - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinitionBuilder() -{ - Map = orders => from order in orders - select new { order.OrderedAt } -} - .ToIndexDefinition(new DocumentConventions()); - -indexDefinition.Name = "Orders/ByOrderDate"; - -// Configure whether the index should process data from archived documents: -// ======================================================================== -indexDefinition.ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - ArchivedDataProcessingBehavior.IncludeArchived; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - - -When a static-index is configured to include **both** archived and non-archived documents in its processing, -you can also apply custom logic based on the presence of the `@archived` metadata property. - -For example: - - - - -{`public class Orders_ByArchivedStatus : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public bool? isArchived { get; set; } - public DateTime? OrderDate { get; set; } - public string ShipToCountry { get; set; } - } - - public Orders_ByArchivedStatus() - { - Map = orders => from order in orders - let metadata = MetadataFor(order) - - // Retrieve the '@archived' metadata property from the document: - let archivedProperty = - metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) - // Alternative syntax: - // let archivedProperty = - // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] - - select new IndexEntry - { - // Index whether the document is archived: - isArchived = archivedProperty == true, - - // Index the order date only if the document is archived: - OrderDate = archivedProperty == true ? order.OrderedAt : null, - - // Index the destination country only if the document is not archived: - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByArchivedStatus_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - var metadata = metadataFor(order); - var archivedProperty = metadata['@archived']; - - var isArchived = (archivedProperty === true); - - var orderDate = isArchived ? order.OrderedAt : null; - var shipToCountry = !isArchived ? order.ShipTo.Country : null; - - return { - IsArchived: isArchived, - OrderDate: orderDate, - ShipToCountry: shipToCountry - }; - })" - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "Orders/ByArchivedStatus", - - Maps = new HashSet - { - @"from order in docs.Orders - let metadata = MetadataFor(order) - let archivedProperty = (bool?)metadata[""@archived""] - - select new - { - IsArchived = archivedProperty == true, - OrderDate = archivedProperty == true ? order.OrderedAt : null, - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }" - }, - - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - -##### Configuring archived document processing for a static index - from the Studio - -You can configure how a static index handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - -![Configure index](./assets/configure-static-index.png) - -1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, - or create a new index. -2. Scroll down and open the **Archived Data** tab. -3. Click to select how this index should process archived documents: - * **Default**: The index will use the behavior set by the global configuration. - * **Exclude Archived**: Index only non-archived documents. - * **Include Archived**: Index both archived and non-archived documents. - * **Archived Only**: Index only archived documents. - -![Processing options](./assets/processing-options.png) - - - -## Archived documents and querying - -* **Full collection queries**: - * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. - * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. - * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). - -* **Dynamic queries (auto-indexes)**: - * When making a dynamic query, RavenDB creates an auto-index to serve it. - Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. - * Once created, the auto-index retains that behavior. - Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. - * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). - -* **Querying static-indexes**: - * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. - The index behavior is determined by: - * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - - * the explicit setting in the index definition, which overrides the global configuration key. - * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. - - - -## Archived documents and subscriptions - -* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. -* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. - This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. -* **Configuring the subscription task behavior**: - * **At the database level or server-wide**: - To control whether queries in data subscription tasks process archived documents, - set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide - (default: `ExcludeArchived`). - * **Per task**: - You can override this global behavior per data subscription task directly in the task definition, - using the Client API or from the Studio (see the examples below). -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the subscription query. - * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. - * `ArchivedOnly`: only archived documents are processed by the subscription query. -##### Configuring archived document processing for a data subscription task - from the Client API - -You can configure how a subscription task handles archived documents when creating the subscription using the Client API. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - Query = "from Orders", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - - -##### Configuring archived document processing for a data subscription task - from the Studio - -You can configure how a subscription task handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - -![Configure subscription](./assets/configure-subscription.png) - -1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, - or create a new subscription. -2. Click to select how the subscription query should process archived documents: - * **Default**: The subscription will use the behavior set by the global configuration. - * **Exclude Archived**: Process only non-archived documents. - * **Include Archived**: Process both archived and non-archived documents. - * **Archived Only**: Process only archived documents. - - - -## Archived documents and document extensions - -* **Attachments**: - * Attachments are Not archived (compressed), even if the document they belong to is archived. - -* **Counters**: - * Counters are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Time series**: - * Time series are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Revisions**: - * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. - * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. - - - -## Archived documents and smuggler (export/import) - -You can control whether archived documents are included when exporting or importing a database. -##### Export/Import archived documents - from the Client API - -[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. -By default, archived documents are **included** in the operation. - - - -In this example, exported data **excludes** archived documents: - - - -{`var exportOperation = store.Smuggler.ExportAsync( - new DatabaseSmugglerExportOptions() - \{ - // Export only non-archived documents: - IncludeArchived = false - \}, "DestinationFilePath"); -`} - - - - - - - -In this example, imported data **includes** archived documents: - - - -{`var importOperation = store.Smuggler.ImportAsync( - new DatabaseSmugglerImportOptions() - \{ - // Include archived documents in the import: - IncludeArchived = true - \}, "SourceFilePath"); -`} - - - - -##### Export archived documents - from the Studio - -![Export archived documents](./assets/export-archived-documents.png) - -1. Go to **Tasks > Export Database**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. -##### Import archived documents - from the Studio - -![Import archived documents](./assets/import-archived-documents.png) - -1. Go to **Tasks > Import Data**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. - - - -## Archived documents and expiration - -* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). - -* For example, a document can be scheduled to be archived after six months and expired after one year. - This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, - and eventually remove documents that are no longer needed. - -* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` - to schedule it for archiving and expiration, respectively: - - - -{`\{ - "Name": "Wilman Kala", - "Phone": "90-224 8858", - ... - "@metadata": \{ - "@archive-at": "2026-01-06T22:45:30.018Z", - "@expires": "2026-07-06T22:45:30.018Z", - "@collection": "Companies", - ... - \} -\} -`} - - - - - -## Archived documents and ETL - -* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) - for the existence of the `@archived: true` property, which indicates that the document is archived. - Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. - -* With [RavenDB ETL](../server/ongoing-tasks/etl/raven.mdx), documents that are archived in the source database and sent to the target - are not archived in the destination database. - -* In the following example, the ETL script checks whether the document is archived, and skips it if it is: - - - -{`var isArchived = this['@metadata']['@archived']; - -if (isArchived === true) \{ - return; // Do not process archived documents -\} - -// Transfer only non-archived documents to the target -loadToOrders(this); -`} - - - - - -## Archived documents and backup - -* Archived documents are included in database backups (both _logical backups_ and _snapshots_), - no special configuration is required. - -* When restoring a database from a backup, archived documents are restored as well, - and their archived status is preserved. - - - -## Archived documents and replication - -Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, -[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - -no special configuration is required. - - - -## Archived documents and patching - -* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: - [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). - [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). - -* Patching is used to **unarchive** documents. - See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). - -* When **cloning** an archived document using the `put` method within a patching script - (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, - and the `@archived: true` property will be removed from the cloned document. - - - - diff --git a/versioned_docs/version-6.2/data-archival/_enable-data-archiving-csharp.mdx b/versioned_docs/version-6.2/data-archival/_enable-data-archiving-csharp.mdx deleted file mode 100644 index 4b2741bca0..0000000000 --- a/versioned_docs/version-6.2/data-archival/_enable-data-archiving-csharp.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, data archiving is disabled. - To use the archiving feature, you must first **enable** it. - -* When configuring the feature, - you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. - -* Once enabled, the archiving task runs periodically at the configured frequency, - scanning the database for documents that have been scheduled for archival. - Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). - -* In this article: - * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) - * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) - - -## Enable archiving - from the Client API - -Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. -**Example**: - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.Send -store.Maintenance.Send(configureArchivalOp); -`} - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.SendAsync -await store.Maintenance.SendAsync(configureArchivalOp); -`} - - - -**Syntax**: - - - -{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) -`} - - - - - -{`public class DataArchivalConfiguration -\{ - public bool Disabled \{ get; set; \} - public long? ArchiveFrequencyInSec \{ get; set; \} - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | -| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | -| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | - - - -## Enable archiving - from the Studio - -![Enable archiving](./assets/enable-archiving.png) - -1. Go to **Settings > Data Archival**. -2. Toggle on to enable data archival. -3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. - Default is 60 seconds. -4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. -5. Click Save to apply your settings. - - - - diff --git a/versioned_docs/version-6.2/data-archival/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-6.2/data-archival/_schedule-document-archiving-csharp.mdx deleted file mode 100644 index cd81710280..0000000000 --- a/versioned_docs/version-6.2/data-archival/_schedule-document-archiving-csharp.mdx +++ /dev/null @@ -1,274 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents cannot be archived directly - they must be scheduled for archival. - To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). - This can be done in several ways, as described in this article. - -* **Note**: - Just scheduling a document for archival does Not archive it at the specified time. - Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). - This task periodically scans the database for documents scheduled for archival. - The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). - -* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. - The `@archive-at` metadata property will then be replaced with `@archived: true`. - -* You can schedule documents for archival even if the archiving feature is not yet enabled. - These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. -* In this article: - * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) - * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) - * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) - * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) - - -## Schedule a SINGLE document for archiving - from the Client API - -To schedule a single document for archival from the Client API, -add the `@archive-at` property directly to the document metadata as follows: - - - - -{`using (var session = store.OpenSession()) -{ - // Load the document to schedule for archiving - var company = session.Load("companies/91-A"); - - // Access the document's metadata - var metadata = session.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - // Load the document to schedule for archiving - var company = await asyncSession.LoadAsync("companies/91-A"); - - // Access the document's metadata - var metadata = asyncSession.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - -Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - - - -## Schedule a SINGLE document for archiving - from the Studio - -* To schedule a single document for archival from the Studio: - * Open the Document view. - * Add the `@archive-at` property to the document's metadata. - * Set its value to the desired archive time in UTC format. - * Save the document. - -![Schedule a document for archiving](./assets/schedule-document-for-archiving.png) - -1. This is the `@archive-at` property that was added to the document's metadata. - E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` -2. After saving the document, the Studio displays the time remaining until the document is archived. - - - -## Schedule MULTIPLE documents for archiving - from the Client API - -* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. - -* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. - In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). - -* When the patch operation is executed, - the server will add the `@archive-at` property to the metadata of all documents that match the query filter. -**Example:** - -The following example schedules all orders that were made at least a year ago for archival. -The **patch query** filters for these older orders. -Any document matching the query is then scheduled for archival by the **patch script**. - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - // The patch query: - // ================ - from Orders - where OrderedAt < '{oldDateString}' - update {{ - // The patch script - schedule for archival: - // ========================================= - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < '{oldDateString}' - update {{ - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.archiveAt(doc, utcDateTimeString) -`} - - - -| Parameter | Type | Description | -|-----------------------|-------------|--------------------------------------------------------------------------------------| -| **doc** | `object` | The document to schedule for archiving. | -| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | - -To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). - - - -## Schedule MULTIPLE documents for archiving - from the Studio - -* To schedule multiple documents for archiving from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. - -![Schedule multiple documents for archiving](./assets/schedule-multiple-documents-for-archiving.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - - diff --git a/versioned_docs/version-6.2/data-archival/_unarchiving-documents-csharp.mdx b/versioned_docs/version-6.2/data-archival/_unarchiving-documents-csharp.mdx deleted file mode 100644 index 1f12e49710..0000000000 --- a/versioned_docs/version-6.2/data-archival/_unarchiving-documents-csharp.mdx +++ /dev/null @@ -1,230 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Archived documents can be unarchived at any time. - -* The archiving feature does Not need to be enabled to unarchive documents. - Any previously archived document can be unarchived, regardless of the feature's current state. - -* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. - This will not clear the internal archived status of the document. - To properly unarchive a document, use the `archived.unarchive()` method as described below. - -* In this article: - * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) - * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) - * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) - - -## Unarchive documents - from the Client API - -* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, - which targets one or more documents based on the patch query. - -* You can apply any filtering condition within the query to target only the documents you want to unarchive. - -* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents - that match the **patch query**. -**Example:** - -The following operation will unarchive ALL archived documents in the _Orders_ collection. - - - - -{`// Define the patch query string -string patchByQuery = @" - // The patch query: - // ================ - from Orders - update - { - // The patch script: - // ================= - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.unarchive(doc) -`} - - - -| Parameter | Type | Description | -|------------|----------|----------------------------| -| **doc** | `object` | The document to unarchive. | - - - -## Unarchive documents - from the Studio - -* To unarchive documents from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.unarchive()` method. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. -It will unarchive all archived documents in the _Orders_ collection. - -![Unarchive documents](./assets/unarchive-documents.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - -## Unarchiving documents with index-based patch queries - -* When running a patch query to unarchive documents over an index, - you need to consider the index configuration regarding archived documents. - -* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - - because those documents are not included in the index. - As a result, no documents will be unarchived by the patch operation. - -* For example, the following patch query uses a dynamic query that creates an auto-index. - If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, - then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - - and the patch operation will not unarchive any documents. - - - -{`string patchByQuery = @" - // This filtering query creates an auto-index: - // =========================================== - from Orders - where ShipTo.Country == 'USA' - update - \{ - archived.unarchive(this) - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - -Two possible workarounds are: - -1. **Configure the index to include archived documents**: - This ensures archived documents are included in the index and can be matched by the patch query. - Use this option only if including archived documents in the index aligns with your indexing strategy. - - **For auto-indexes**: - Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. - **For static-indexes**: - Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, - or - configure the definition of the specific static-index to include archived documents. - See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). - -2. **Use a collection query instead of an index query**: - Run a simple collection-based query that does not rely on an index. - Apply your filtering logic inside the patch script to unarchive only the relevant documents. - - For example: - - -{`string patchByQuery = @" - // Perform a collection query: - // =========================== - from Orders as order - update - \{ - // Filter documents inside the script: - // =================================== - if (order.ShipTo.City == 'New York') - \{ - archived.unarchive(this) - \} - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - - - - - diff --git a/versioned_docs/version-6.2/data-archival/archived-documents-and-other-features.mdx b/versioned_docs/version-6.2/data-archival/archived-documents-and-other-features.mdx index 6cf644a121..6e66d0d452 100644 --- a/versioned_docs/version-6.2/data-archival/archived-documents-and-other-features.mdx +++ b/versioned_docs/version-6.2/data-archival/archived-documents-and-other-features.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ArchivedDocumentsAndOtherFeaturesCsharp from './_archived-documents-and-other-features-csharp.mdx'; +import ArchivedDocumentsAndOtherFeaturesCsharp from './content/_archived-documents-and-other-features-csharp.mdx'; diff --git a/versioned_docs/version-6.2/data-archival/content/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-6.2/data-archival/content/_archived-documents-and-other-features-csharp.mdx new file mode 100644 index 0000000000..2ffc1c20e3 --- /dev/null +++ b/versioned_docs/version-6.2/data-archival/content/_archived-documents-and-other-features-csharp.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), + RavenDB features can detect these documents and handle them in different ways. + +* Some features, like indexes and data subscriptions, provide native support for configuring whether to: + * **Exclude** archived documents from processing, reducing index size and improving query relevance. + * **Include** only archived documents, for tasks that target archived data specifically. + * **Process both** archived and non-archived documents when needed. + +* Other features can manage archived documents differently based on their purpose. For example: + * ETL tasks can skip or selectively process archived documents. + * Archived documents can be included or excluded when exporting or importing data. + +* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. + +* Learn more below about how various RavenDB features interact with archived documents. +* In this article: + * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) + * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) + * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) + * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) + * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) + * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) + * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) + * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) + * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) + * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) + + +## Archived documents and indexing + +* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. +* Archiving documents and excluding them from indexing can be an effective way to maintain performance. + By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. + This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. +* **Configuring indexing behavior - Static indexes**: + * **At the database level or server-wide**: + To control whether static indexes process archived documents from the source collection, + set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) + configuration key at either the database level or server-wide (default: `ExcludeArchived`). + * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. + This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. + * **Per index**: + You can override this global behavior per-index directly in the index definition, using the Client API from the Studio + (see the examples below). + +* **Configuring indexing behavior - Auto indexes:** + * **At the database level or server-wide**: + To control whether auto-indexes process archived documents at the database level or server-wide, + set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). + * **Per index**: + Unlike static indexes, you cannot configure this behavior per auto-index, + because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the index. + * `IncludeArchived`: both archived and non-archived documents are processed by the index. + * `ArchivedOnly`: only archived documents are processed by the index. +##### Configuring archived document processing for a static index - from the Client API + +You can configure how a static index handles archived documents when creating the index using the Client API. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`public class Orders_ByOrderDate : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public DateTime OrderDate { get; set; } + } + + public Orders_ByOrderDate() + { + Map = orders => from order in orders + select new IndexEntry + { + OrderDate = order.OrderedAt + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByOrderDate_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + return { + OrderDate: order.OrderedAt + }; + })" + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinitionBuilder() +{ + Map = orders => from order in orders + select new { order.OrderedAt } +} + .ToIndexDefinition(new DocumentConventions()); + +indexDefinition.Name = "Orders/ByOrderDate"; + +// Configure whether the index should process data from archived documents: +// ======================================================================== +indexDefinition.ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + ArchivedDataProcessingBehavior.IncludeArchived; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + + +When a static-index is configured to include **both** archived and non-archived documents in its processing, +you can also apply custom logic based on the presence of the `@archived` metadata property. + +For example: + + + + +{`public class Orders_ByArchivedStatus : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public bool? isArchived { get; set; } + public DateTime? OrderDate { get; set; } + public string ShipToCountry { get; set; } + } + + public Orders_ByArchivedStatus() + { + Map = orders => from order in orders + let metadata = MetadataFor(order) + + // Retrieve the '@archived' metadata property from the document: + let archivedProperty = + metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) + // Alternative syntax: + // let archivedProperty = + // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] + + select new IndexEntry + { + // Index whether the document is archived: + isArchived = archivedProperty == true, + + // Index the order date only if the document is archived: + OrderDate = archivedProperty == true ? order.OrderedAt : null, + + // Index the destination country only if the document is not archived: + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByArchivedStatus_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + var metadata = metadataFor(order); + var archivedProperty = metadata['@archived']; + + var isArchived = (archivedProperty === true); + + var orderDate = isArchived ? order.OrderedAt : null; + var shipToCountry = !isArchived ? order.ShipTo.Country : null; + + return { + IsArchived: isArchived, + OrderDate: orderDate, + ShipToCountry: shipToCountry + }; + })" + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "Orders/ByArchivedStatus", + + Maps = new HashSet + { + @"from order in docs.Orders + let metadata = MetadataFor(order) + let archivedProperty = (bool?)metadata[""@archived""] + + select new + { + IsArchived = archivedProperty == true, + OrderDate = archivedProperty == true ? order.OrderedAt : null, + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }" + }, + + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + +##### Configuring archived document processing for a static index - from the Studio + +You can configure how a static index handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + +![Configure index](../assets/configure-static-index.png) + +1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, + or create a new index. +2. Scroll down and open the **Archived Data** tab. +3. Click to select how this index should process archived documents: + * **Default**: The index will use the behavior set by the global configuration. + * **Exclude Archived**: Index only non-archived documents. + * **Include Archived**: Index both archived and non-archived documents. + * **Archived Only**: Index only archived documents. + +![Processing options](../assets/processing-options.png) + + + +## Archived documents and querying + +* **Full collection queries**: + * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. + * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. + * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). + +* **Dynamic queries (auto-indexes)**: + * When making a dynamic query, RavenDB creates an auto-index to serve it. + Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. + * Once created, the auto-index retains that behavior. + Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. + * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). + +* **Querying static-indexes**: + * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. + The index behavior is determined by: + * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - + * the explicit setting in the index definition, which overrides the global configuration key. + * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. + + + +## Archived documents and subscriptions + +* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. +* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. + This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. +* **Configuring the subscription task behavior**: + * **At the database level or server-wide**: + To control whether queries in data subscription tasks process archived documents, + set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide + (default: `ExcludeArchived`). + * **Per task**: + You can override this global behavior per data subscription task directly in the task definition, + using the Client API or from the Studio (see the examples below). +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the subscription query. + * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. + * `ArchivedOnly`: only archived documents are processed by the subscription query. +##### Configuring archived document processing for a data subscription task - from the Client API + +You can configure how a subscription task handles archived documents when creating the subscription using the Client API. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + Query = "from Orders", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + + +##### Configuring archived document processing for a data subscription task - from the Studio + +You can configure how a subscription task handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + +![Configure subscription](../assets/configure-subscription.png) + +1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, + or create a new subscription. +2. Click to select how the subscription query should process archived documents: + * **Default**: The subscription will use the behavior set by the global configuration. + * **Exclude Archived**: Process only non-archived documents. + * **Include Archived**: Process both archived and non-archived documents. + * **Archived Only**: Process only archived documents. + + + +## Archived documents and document extensions + +* **Attachments**: + * Attachments are Not archived (compressed), even if the document they belong to is archived. + +* **Counters**: + * Counters are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Time series**: + * Time series are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Revisions**: + * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. + * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. + + + +## Archived documents and smuggler (export/import) + +You can control whether archived documents are included when exporting or importing a database. +##### Export/Import archived documents - from the Client API + +[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. +By default, archived documents are **included** in the operation. + + + +In this example, exported data **excludes** archived documents: + + + +{`var exportOperation = store.Smuggler.ExportAsync( + new DatabaseSmugglerExportOptions() + \{ + // Export only non-archived documents: + IncludeArchived = false + \}, "DestinationFilePath"); +`} + + + + + + + +In this example, imported data **includes** archived documents: + + + +{`var importOperation = store.Smuggler.ImportAsync( + new DatabaseSmugglerImportOptions() + \{ + // Include archived documents in the import: + IncludeArchived = true + \}, "SourceFilePath"); +`} + + + + +##### Export archived documents - from the Studio + +![Export archived documents](../assets/export-archived-documents.png) + +1. Go to **Tasks > Export Database**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. +##### Import archived documents - from the Studio + +![Import archived documents](../assets/import-archived-documents.png) + +1. Go to **Tasks > Import Data**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. + + + +## Archived documents and expiration + +* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). + +* For example, a document can be scheduled to be archived after six months and expired after one year. + This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, + and eventually remove documents that are no longer needed. + +* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` + to schedule it for archiving and expiration, respectively: + + + +{`\{ + "Name": "Wilman Kala", + "Phone": "90-224 8858", + ... + "@metadata": \{ + "@archive-at": "2026-01-06T22:45:30.018Z", + "@expires": "2026-07-06T22:45:30.018Z", + "@collection": "Companies", + ... + \} +\} +`} + + + + + +## Archived documents and ETL + +* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) + for the existence of the `@archived: true` property, which indicates that the document is archived. + Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. + +* With [RavenDB ETL](../server/ongoing-tasks/etl/raven.mdx), documents that are archived in the source database and sent to the target + are not archived in the destination database. + +* In the following example, the ETL script checks whether the document is archived, and skips it if it is: + + + +{`var isArchived = this['@metadata']['@archived']; + +if (isArchived === true) \{ + return; // Do not process archived documents +\} + +// Transfer only non-archived documents to the target +loadToOrders(this); +`} + + + + + +## Archived documents and backup + +* Archived documents are included in database backups (both _logical backups_ and _snapshots_), + no special configuration is required. + +* When restoring a database from a backup, archived documents are restored as well, + and their archived status is preserved. + + + +## Archived documents and replication + +Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, +[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - +no special configuration is required. + + + +## Archived documents and patching + +* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: + [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). + [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). + +* Patching is used to **unarchive** documents. + See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). + +* When **cloning** an archived document using the `put` method within a patching script + (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, + and the `@archived: true` property will be removed from the cloned document. + + + + diff --git a/versioned_docs/version-6.2/data-archival/content/_enable-data-archiving-csharp.mdx b/versioned_docs/version-6.2/data-archival/content/_enable-data-archiving-csharp.mdx new file mode 100644 index 0000000000..cdcdfecd0f --- /dev/null +++ b/versioned_docs/version-6.2/data-archival/content/_enable-data-archiving-csharp.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, data archiving is disabled. + To use the archiving feature, you must first **enable** it. + +* When configuring the feature, + you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. + +* Once enabled, the archiving task runs periodically at the configured frequency, + scanning the database for documents that have been scheduled for archival. + Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). + +* In this article: + * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) + * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) + + +## Enable archiving - from the Client API + +Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. +**Example**: + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.Send +store.Maintenance.Send(configureArchivalOp); +`} + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.SendAsync +await store.Maintenance.SendAsync(configureArchivalOp); +`} + + + +**Syntax**: + + + +{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) +`} + + + + + +{`public class DataArchivalConfiguration +\{ + public bool Disabled \{ get; set; \} + public long? ArchiveFrequencyInSec \{ get; set; \} + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | +| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | +| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | + + + +## Enable archiving - from the Studio + +![Enable archiving](../assets/enable-archiving.png) + +1. Go to **Settings > Data Archival**. +2. Toggle on to enable data archival. +3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. + Default is 60 seconds. +4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. +5. Click Save to apply your settings. + + + + diff --git a/versioned_docs/version-6.2/data-archival/content/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-6.2/data-archival/content/_schedule-document-archiving-csharp.mdx new file mode 100644 index 0000000000..0414d08e3f --- /dev/null +++ b/versioned_docs/version-6.2/data-archival/content/_schedule-document-archiving-csharp.mdx @@ -0,0 +1,274 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents cannot be archived directly - they must be scheduled for archival. + To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). + This can be done in several ways, as described in this article. + +* **Note**: + Just scheduling a document for archival does Not archive it at the specified time. + Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). + This task periodically scans the database for documents scheduled for archival. + The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). + +* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. + The `@archive-at` metadata property will then be replaced with `@archived: true`. + +* You can schedule documents for archival even if the archiving feature is not yet enabled. + These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. +* In this article: + * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) + * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) + * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) + * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) + + +## Schedule a SINGLE document for archiving - from the Client API + +To schedule a single document for archival from the Client API, +add the `@archive-at` property directly to the document metadata as follows: + + + + +{`using (var session = store.OpenSession()) +{ + // Load the document to schedule for archiving + var company = session.Load("companies/91-A"); + + // Access the document's metadata + var metadata = session.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + // Load the document to schedule for archiving + var company = await asyncSession.LoadAsync("companies/91-A"); + + // Access the document's metadata + var metadata = asyncSession.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + +Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + + + +## Schedule a SINGLE document for archiving - from the Studio + +* To schedule a single document for archival from the Studio: + * Open the Document view. + * Add the `@archive-at` property to the document's metadata. + * Set its value to the desired archive time in UTC format. + * Save the document. + +![Schedule a document for archiving](../assets/schedule-document-for-archiving.png) + +1. This is the `@archive-at` property that was added to the document's metadata. + E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` +2. After saving the document, the Studio displays the time remaining until the document is archived. + + + +## Schedule MULTIPLE documents for archiving - from the Client API + +* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. + +* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. + In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). + +* When the patch operation is executed, + the server will add the `@archive-at` property to the metadata of all documents that match the query filter. +**Example:** + +The following example schedules all orders that were made at least a year ago for archival. +The **patch query** filters for these older orders. +Any document matching the query is then scheduled for archival by the **patch script**. + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + // The patch query: + // ================ + from Orders + where OrderedAt < '{oldDateString}' + update {{ + // The patch script - schedule for archival: + // ========================================= + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < '{oldDateString}' + update {{ + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.archiveAt(doc, utcDateTimeString) +`} + + + +| Parameter | Type | Description | +|-----------------------|-------------|--------------------------------------------------------------------------------------| +| **doc** | `object` | The document to schedule for archiving. | +| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | + +To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). + + + +## Schedule MULTIPLE documents for archiving - from the Studio + +* To schedule multiple documents for archiving from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. + +![Schedule multiple documents for archiving](../assets/schedule-multiple-documents-for-archiving.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + + diff --git a/versioned_docs/version-6.2/data-archival/content/_unarchiving-documents-csharp.mdx b/versioned_docs/version-6.2/data-archival/content/_unarchiving-documents-csharp.mdx new file mode 100644 index 0000000000..faac23a4e8 --- /dev/null +++ b/versioned_docs/version-6.2/data-archival/content/_unarchiving-documents-csharp.mdx @@ -0,0 +1,230 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Archived documents can be unarchived at any time. + +* The archiving feature does Not need to be enabled to unarchive documents. + Any previously archived document can be unarchived, regardless of the feature's current state. + +* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. + This will not clear the internal archived status of the document. + To properly unarchive a document, use the `archived.unarchive()` method as described below. + +* In this article: + * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) + * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) + * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) + + +## Unarchive documents - from the Client API + +* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, + which targets one or more documents based on the patch query. + +* You can apply any filtering condition within the query to target only the documents you want to unarchive. + +* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents + that match the **patch query**. +**Example:** + +The following operation will unarchive ALL archived documents in the _Orders_ collection. + + + + +{`// Define the patch query string +string patchByQuery = @" + // The patch query: + // ================ + from Orders + update + { + // The patch script: + // ================= + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.unarchive(doc) +`} + + + +| Parameter | Type | Description | +|------------|----------|----------------------------| +| **doc** | `object` | The document to unarchive. | + + + +## Unarchive documents - from the Studio + +* To unarchive documents from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.unarchive()` method. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. +It will unarchive all archived documents in the _Orders_ collection. + +![Unarchive documents](../assets/unarchive-documents.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + +## Unarchiving documents with index-based patch queries + +* When running a patch query to unarchive documents over an index, + you need to consider the index configuration regarding archived documents. + +* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - + because those documents are not included in the index. + As a result, no documents will be unarchived by the patch operation. + +* For example, the following patch query uses a dynamic query that creates an auto-index. + If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, + then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - + and the patch operation will not unarchive any documents. + + + +{`string patchByQuery = @" + // This filtering query creates an auto-index: + // =========================================== + from Orders + where ShipTo.Country == 'USA' + update + \{ + archived.unarchive(this) + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + +Two possible workarounds are: + +1. **Configure the index to include archived documents**: + This ensures archived documents are included in the index and can be matched by the patch query. + Use this option only if including archived documents in the index aligns with your indexing strategy. + + **For auto-indexes**: + Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. + **For static-indexes**: + Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, + or - configure the definition of the specific static-index to include archived documents. + See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). + +2. **Use a collection query instead of an index query**: + Run a simple collection-based query that does not rely on an index. + Apply your filtering logic inside the patch script to unarchive only the relevant documents. + + For example: + + +{`string patchByQuery = @" + // Perform a collection query: + // =========================== + from Orders as order + update + \{ + // Filter documents inside the script: + // =================================== + if (order.ShipTo.City == 'New York') + \{ + archived.unarchive(this) + \} + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + + + + + diff --git a/versioned_docs/version-6.2/data-archival/enable-data-archiving.mdx b/versioned_docs/version-6.2/data-archival/enable-data-archiving.mdx index 5792991f3d..8b1d5eb068 100644 --- a/versioned_docs/version-6.2/data-archival/enable-data-archiving.mdx +++ b/versioned_docs/version-6.2/data-archival/enable-data-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableDataArchivingCsharp from './_enable-data-archiving-csharp.mdx'; +import EnableDataArchivingCsharp from './content/_enable-data-archiving-csharp.mdx'; diff --git a/versioned_docs/version-6.2/data-archival/schedule-document-archiving.mdx b/versioned_docs/version-6.2/data-archival/schedule-document-archiving.mdx index c22e6a21ed..09b032fc17 100644 --- a/versioned_docs/version-6.2/data-archival/schedule-document-archiving.mdx +++ b/versioned_docs/version-6.2/data-archival/schedule-document-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ScheduleDocumentArchivingCsharp from './_schedule-document-archiving-csharp.mdx'; +import ScheduleDocumentArchivingCsharp from './content/_schedule-document-archiving-csharp.mdx'; diff --git a/versioned_docs/version-6.2/data-archival/unarchiving-documents.mdx b/versioned_docs/version-6.2/data-archival/unarchiving-documents.mdx index 808769d015..89afcf916d 100644 --- a/versioned_docs/version-6.2/data-archival/unarchiving-documents.mdx +++ b/versioned_docs/version-6.2/data-archival/unarchiving-documents.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UnarchivingDocumentsCsharp from './_unarchiving-documents-csharp.mdx'; +import UnarchivingDocumentsCsharp from './content/_unarchiving-documents-csharp.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/bulk-insert.mdx b/versioned_docs/version-6.2/document-extensions/attachments/bulk-insert.mdx index c763b6a3ca..296538d2fa 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/bulk-insert.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/bulk-insert.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BulkInsertCsharp from './_bulk-insert-csharp.mdx'; -import BulkInsertPython from './_bulk-insert-python.mdx'; -import BulkInsertNodejs from './_bulk-insert-nodejs.mdx'; +import BulkInsertCsharp from './content/_bulk-insert-csharp.mdx'; +import BulkInsertPython from './content/_bulk-insert-python.mdx'; +import BulkInsertNodejs from './content/_bulk-insert-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_bulk-insert-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_bulk-insert-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-php.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-php.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_copying-moving-renaming-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_copying-moving-renaming-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_deleting-php.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_deleting-php.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_deleting-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_deleting-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_deleting-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_indexing-php.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_indexing-php.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_indexing-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_indexing-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_loading-php.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_loading-php.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_loading-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_loading-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_loading-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_loading-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_storing-php.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_storing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_storing-php.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_storing-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_storing-python.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_storing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_storing-python.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_storing-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-6.2/document-extensions/attachments/copying-moving-renaming.mdx index 5d9756c7ff..dd66ad7797 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; -import CopyingMovingRenamingPython from './_copying-moving-renaming-python.mdx'; -import CopyingMovingRenamingPhp from './_copying-moving-renaming-php.mdx'; -import CopyingMovingRenamingNodejs from './_copying-moving-renaming-nodejs.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingPython from './content/_copying-moving-renaming-python.mdx'; +import CopyingMovingRenamingPhp from './content/_copying-moving-renaming-php.mdx'; +import CopyingMovingRenamingNodejs from './content/_copying-moving-renaming-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/deleting.mdx b/versioned_docs/version-6.2/document-extensions/attachments/deleting.mdx index 412aa66a67..604c4058e7 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/deleting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingPython from './_deleting-python.mdx'; -import DeletingPhp from './_deleting-php.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingPython from './content/_deleting-python.mdx'; +import DeletingPhp from './content/_deleting-php.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/indexing.mdx b/versioned_docs/version-6.2/document-extensions/attachments/indexing.mdx index d49e97610c..8fca84b22e 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/loading.mdx b/versioned_docs/version-6.2/document-extensions/attachments/loading.mdx index b845db6865..6c82d701c2 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/storing.mdx b/versioned_docs/version-6.2/document-extensions/attachments/storing.mdx index 5e877c3b82..cb3e3b93d1 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/storing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringPython from './_storing-python.mdx'; -import StoringPhp from './_storing-php.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringPython from './content/_storing-python.mdx'; +import StoringPhp from './content/_storing-php.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-6.2/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-6.2/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-6.2/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_counters-and-other-features-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_create-or-modify-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_delete-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_delete-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_delete-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_delete-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_delete-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_delete-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_delete-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_delete-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_including-counters-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_including-counters-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_including-counters-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_including-counters-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_including-counters-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_including-counters-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_including-counters-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_including-counters-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_including-counters-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_including-counters-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_including-counters-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_indexing-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_indexing-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_indexing-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_indexing-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_overview-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_overview-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_overview-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_overview-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_overview-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_overview-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_overview-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-php.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-php.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-python.mdx b/versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/counters/_retrieve-counter-values-python.mdx rename to versioned_docs/version-6.2/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-6.2/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-6.2/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/delete.mdx b/versioned_docs/version-6.2/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/including-counters.mdx b/versioned_docs/version-6.2/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/including-counters.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/indexing.mdx b/versioned_docs/version-6.2/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/overview.mdx b/versioned_docs/version-6.2/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-6.2/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/versioned_docs/version-6.2/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-6.2/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 4365c1079c..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,321 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index 8b480d9db1..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,318 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_overview-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 0dd4ed178c..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,281 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created automatically or manually: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - -##### Conflict Revisions - -Revisions created for **conflicting documents** are a special case that is not covered in this article. - -* Conflict revisions are **enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) -* Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. - Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions_enable-revisions.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions_create-document.png) - -3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions_document-created.png) - - (Click the _See the current document_ button to return to the parent document view.) - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions_modify-document.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions_revisions-bin.png) - -6. **Restore the document**. - To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. - - The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. - Opening the document's Revisions tab will display the whole audit trail, - including the delete-revision created when the old document was deleted and the revision created when the new document was created. - - ![Restored Revisions](./assets/revisions_restored.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), - and a "Delete-Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions tab in the document view. - -![Create a revision manually](./assets/revisions_create-revision-manually.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 1906658a54..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index 3c8783a8ad..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index d42399f08e..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/_overview-python.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/delete-revisions.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/delete-revisions.mdx index 52d57a6d9e..6ac42ce584 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/delete-revisions.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/delete-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteRevisionsCsharp from './_delete-revisions-csharp.mdx'; +import DeleteRevisionsCsharp from './content/_delete-revisions-csharp.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_counting-python.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_including-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-php.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/client-api/session/_loading-python.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..0f66fc334b --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,321 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..b57988e8d8 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,318 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..63987fad60 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,281 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions.mdx) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **[Enforce Configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) is applied**. + Enforcing the configuration applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions_enable-revisions.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions_create-document.png) + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions_document-created.png) + + (Click the _See the current document_ button to return to the parent document view.) + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions_modify-document.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions_revisions-bin.png) + +6. **Restore the document**. + To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted. + + The revisions of the deleted document will be **restored** from the revisions bin and added to the new document. + Opening the document's Revisions tab will display the whole audit trail, + including the delete-revision created when the old document was deleted and the revision created when the new document was created. + + ![Restored Revisions](../assets/revisions_restored.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions.mdx#revisions-bin), + and a "Delete-Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. + +![Create a revision manually](../assets/revisions_create-revision-manually.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..335c0a220b --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6bf087d689 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..ab3a281b0b --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-6.2/document-extensions/revisions/overview.mdx b/versioned_docs/version-6.2/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/overview.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx deleted file mode 100644 index 1ca0053750..0000000000 --- a/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx +++ /dev/null @@ -1,221 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ContentFrame from '@site/src/components/ContentFrame'; -import Panel from '@site/src/components/Panel'; - - - -* This article describes how to revert specific documents to **specific revisions**. - To revert documents from all collections (or from selected collections) to a **specific point in time**, - see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). - -* In this article: - * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) - * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) - * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) - * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) - * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) - - - - - -* When reverting to a specific revision, - the document content will be overwritten by the content of the specified revision. - -* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: - * **When revisions are ENABLED**: - Reverting the document creates a new revision containing the content of the target revision. - * **When revisions are DISABLED**: - The document is reverted to the target revision without creating a new revision. - -* In addition to the document itself, reverting will impact _Document Extensions_ as follows: - * **Attachments**: - If the target revision owns attachments, they are restored to their state when the revision was created. - * **Counters**: - If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. - * **Time series**: - Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). - - - - - -* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. - -* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). - To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). - -* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. - The document content will be overwritten by the content of the specified revision. - -* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. - -* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, - the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. - ---- - -### How to obtain a revision's change-vector: - -The change-vector of a revision can be obtained via: - - * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) - * Or from the document view in the Studio - -![Get revision CV](./assets/get-cv-for-revision.png) - -1. Go to the Revisions tab in the document view. -2. Click a revision to view -3. The document view will display the content of the revision. - This top label indicates that you are viewing a revision and not the current document. -4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. - - - - - -Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. -In this example, we revert document _orders/1-A_ to its very first revision. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "Orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); -} -``` - - - - - - - -You can use the operation to revert multiple documents. -Note: The documents do not need to belong to the same collection. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - var revisionsMetadata2 = session.Advanced.Revisions - .GetMetadataFor(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "orders/1-A"); - var revisionsMetadata2 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - - - - - - -### `RevertRevisionsByIdOperation` - - -```csharp -Available overloads: -==================== -public RevertRevisionsByIdOperation(string id, string cv); -public RevertRevisionsByIdOperation(Dictionary idToChangeVector); -``` - - -| Parameter | Type | Description | -|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| **id** | `string` | The ID of the document to revert. | -| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | -| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | - - \ No newline at end of file diff --git a/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx new file mode 100644 index 0000000000..df41e24beb --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx @@ -0,0 +1,221 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* This article describes how to revert specific documents to **specific revisions**. + To revert documents from all collections (or from selected collections) to a **specific point in time**, + see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). + +* In this article: + * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) + * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) + * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) + * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) + * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) + + + + + +* When reverting to a specific revision, + the document content will be overwritten by the content of the specified revision. + +* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: + * **When revisions are ENABLED**: + Reverting the document creates a new revision containing the content of the target revision. + * **When revisions are DISABLED**: + The document is reverted to the target revision without creating a new revision. + +* In addition to the document itself, reverting will impact _Document Extensions_ as follows: + * **Attachments**: + If the target revision owns attachments, they are restored to their state when the revision was created. + * **Counters**: + If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. + * **Time series**: + Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). + + + + + +* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. + +* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). + To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). + +* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. + The document content will be overwritten by the content of the specified revision. + +* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. + +* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, + the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. + +--- + +### How to obtain a revision's change-vector: + +The change-vector of a revision can be obtained via: + + * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) + * Or from the document view in the Studio + +![Get revision CV](../assets/get-cv-for-revision.png) + +1. Go to the Revisions tab in the document view. +2. Click a revision to view +3. The document view will display the content of the revision. + This top label indicates that you are viewing a revision and not the current document. +4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. + + + + + +Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. +In this example, we revert document _orders/1-A_ to its very first revision. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "Orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); +} +``` + + + + + + + +You can use the operation to revert multiple documents. +Note: The documents do not need to belong to the same collection. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + var revisionsMetadata2 = session.Advanced.Revisions + .GetMetadataFor(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "orders/1-A"); + var revisionsMetadata2 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + + + + + + +### `RevertRevisionsByIdOperation` + + +```csharp +Available overloads: +==================== +public RevertRevisionsByIdOperation(string id, string cv); +public RevertRevisionsByIdOperation(Dictionary idToChangeVector); +``` + + +| Parameter | Type | Description | +|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| **id** | `string` | The ID of the document to revert. | +| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | +| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | + + \ No newline at end of file diff --git a/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx b/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx index 041ad50de9..3586680073 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevertDocumentsToSpecificRevisionsCsharp from './_revert-documents-to-specific-revisions-csharp.mdx'; +import RevertDocumentsToSpecificRevisionsCsharp from './content/_revert-documents-to-specific-revisions-csharp.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-6.2/document-extensions/revisions/revisions-and-other-features.mdx index dd80b671dc..38db72b2c8 100644 --- a/versioned_docs/version-6.2/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-6.2/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 5972ad8ca5..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,300 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 2c0c4c1a5b..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,257 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index af9e9480f6..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index aa992fed57..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,309 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/javascript-support.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/named-time-series-values.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/get.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/get.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/patch.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/overview.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/overview.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/append.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/append.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_append-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/delete.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/delete.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-names.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/overview.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/patch.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/patch.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/querying.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/querying.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_design-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_design-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_design-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_design-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_indexing-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_indexing-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_indexing-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_indexing-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_indexing-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_indexing-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/_indexing-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/_indexing-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..c0d3e3b2c5 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,300 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..57c5f44e40 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,257 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..7da93ce29a --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..5d3e24fd7f --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,309 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/design.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/design.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/indexing.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/indexing.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 18ae9a014f..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,313 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index 3c635a3470..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,333 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index cb160b6ec6..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,282 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index 2025bccf4a..0000000000 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/choosing-query-range.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_filtering-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..1b0383ae1e --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,313 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..d4b5203c2b --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,333 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..76bcc0b26c --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,282 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..11bb66c408 --- /dev/null +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-php.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-python.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to versioned_docs/version-6.2/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/filtering.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/filtering.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/overview-and-syntax.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/querying/using-indexes.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/querying/using-indexes.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/rollup-and-retention.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/rollup-and-retention.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/document-extensions/timeseries/time-series-and-other-features.mdx b/versioned_docs/version-6.2/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/versioned_docs/version-6.2/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/versioned_docs/version-6.2/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-6.2/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-6.2/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-6.2/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_index-query-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_index-query-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_query-result-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_query-result-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/_stream-result-csharp.mdx b/versioned_docs/version-6.2/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-6.2/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-6.2/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-6.2/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-6.2/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/counters-batch-command-data.mdx b/versioned_docs/version-6.2/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-6.2/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/delete-command-data.mdx b/versioned_docs/version-6.2/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-6.2/glossary/delete-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-6.2/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-6.2/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/index-query.mdx b/versioned_docs/version-6.2/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-6.2/glossary/index-query.mdx +++ b/versioned_docs/version-6.2/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/move-attachment-command-data.mdx b/versioned_docs/version-6.2/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-6.2/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/patch-command-data.mdx b/versioned_docs/version-6.2/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-6.2/glossary/patch-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/put-command-data.mdx b/versioned_docs/version-6.2/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-6.2/glossary/put-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-6.2/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-6.2/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-6.2/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/query-result.mdx b/versioned_docs/version-6.2/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-6.2/glossary/query-result.mdx +++ b/versioned_docs/version-6.2/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/stream-query-statistics.mdx b/versioned_docs/version-6.2/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-6.2/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-6.2/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-6.2/glossary/stream-result.mdx b/versioned_docs/version-6.2/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-6.2/glossary/stream-result.mdx +++ b/versioned_docs/version-6.2/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-6.2/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-6.2/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-nested-data-php.mdx b/versioned_docs/version-6.2/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-nested-data-python.mdx b/versioned_docs/version-6.2/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-6.2/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-6.2/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-related-documents-php.mdx b/versioned_docs/version-6.2/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.2/indexes/_indexing-related-documents-python.mdx b/versioned_docs/version-6.2/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/versioned_docs/version-6.2/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-6.2/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-6.2/indexes/_storing-data-in-index-csharp.mdx deleted file mode 100644 index d588e9caf4..0000000000 --- a/versioned_docs/version-6.2/indexes/_storing-data-in-index-csharp.mdx +++ /dev/null @@ -1,409 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB allows you to store data in a static index. - -* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), - without requiring the server to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - -* In this article: - * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) - * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) - * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) - * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) - - -## What content is stored in the index - -* A static index is defined by its map function which determines the content of each **index-entry**. - Typically, a single index-entry is created for each document from the indexed source collection - - unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. - -* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. - The content of an index-field can be a direct value from the source document field, - or a computed value based on the source document's content. - -* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). - The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. - -* **RavenDB allows you to store the original index-field value in the index**. - **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. - * The tokens (terms) generated by the analyzer are searchable but not stored. - * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) - (by default they are not stored). - -* This behavior is supported by both Lucene and Corax search engines. - - - -## When and why to store data in an index - -* **Store a field in the index if**: - - * **You want to project that field without loading the full document.** - Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. - If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. - * **The index-field is a computed value that you want to return in the query results.** - Normally, querying an index returns matching documents. - But if you're projecting a computed index-field that is Not stored, - you'll need to re-calculate the computed value manually from the documents returned by the query. - Storing the computed field avoids this extra step. - -* **You do not need to store a field in the index in order to**: - - * Filter by the field in a query. - * Perform full-text search on the field. - -* **Disadvantage of storing data in the index**: - - * Increased disk space usage - stored fields take up additional space and increase index size. - - - -## Storing data in index - from the Client API - -To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). -The default is `FieldStorage.No`. -**Index example:** - - - - -{`public class QuantityOrdered_ByCompany : - AbstractIndexCreationTask -{ - // The index-entry: - public class IndexEntry - { - // The index-fields: - public string Company { get; set; } - public string CompanyName { get; set; } - public int TotalItemsOrdered { get; set; } - } - - public QuantityOrdered_ByCompany() - { - Map = orders => from order in orders - select new IndexEntry - { - // 'Company' is a SIMPLE index-field, - // its value is taken directly from the Order document: - Company = order.Company, - - // 'CompanyName' is also considered a simple index-field, - // its value is taken from the related Company document: - CompanyName = LoadDocument(order.Company).Name, - - // 'TotalItemsOrdered' is a COMPUTED index-field: - // (the total quantity of items ordered in an Order document) - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }; - - // Store the calculated 'TotalItemsOrdered' index-field in the index: - // ================================================================== - Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); - - // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: - // ======================================================================================= - Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); - - // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): - // ============================================================================= - Stores.Add(x => x.CompanyName, FieldStorage.Yes); - } -} -`} - - - - -{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask -{ - public QuantityOrdered_ByCompany_JS() - { - Maps = new HashSet() - { - @"map('orders', function(order) { - let company = load(order.Company, 'Companies') - return { - Company: order.Company, - CompanyName: company.Name, - TotalItemsOrdered: order.Lines.reduce(function(total, line) { - return total + line.Quantity; - }, 0) - }; - })" - }; - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - }; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "QuantityOrdered/ByCompany", - - Maps = - { - @"from order in docs.Orders - select new - { - Company = order.Company, - CompanyName = LoadDocument(order.Company, ""Companies"").Name, - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }" - }, - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - } -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -**Querying the index and projecting results:** - - - -* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. - -* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. - The server does Not need to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class NumberOfItemsOrdered -{ - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select TotalItemsOrdered -`} - - - - - - - -* In this query, the projected results are defined by the custom class `ProjectedDetails`. - -* In this case, some of the fields in this class are Not stored in the index, so by default, - the server does need to load the original document from storage to complete the projection. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class ProjectedDetails -{ - // This field was Not stored in the index definition - public string Company { get; set; } - // This field was Not stored in the index definition - public DateTime OrderedAt { get; set; } - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select Company, OrderedAt, TotalItemsOrdered -`} - - - - - - - -## Storing data in index - from the Studio - -To configure index-fields from the Studio, open the _Edit Index_ view: - -![The index](./assets/store-field-in-index-1.png) - -1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). -2. These are the index-fields defined in the index map function. -Scroll down to configure each index-field: - -![Configure index fields](./assets/store-field-in-index-2.png) - -1. Open the _Fields_ tab. -2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. -3. Select _Yes_ from the dropdown to store the field in the index. -4. Here we configure index-field `CompanyName`. -5. This index-field is stored in the index and also configured for full-text search. -When querying the index from the Studio, -you can choose to display the stored index fields in the Results view: - -![Display the stored fields](./assets/store-field-in-index-3.png) - -1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). -2. Open the _Settings_ options. -3. Toggle ON _Show stored index fields only_. -4. When executing the query, - the results will display the stored index-fields for each object returned by the query. - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-6.2/indexes/_using-analyzers-csharp.mdx deleted file mode 100644 index 0c33a1d29f..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-analyzers-csharp.mdx +++ /dev/null @@ -1,691 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - - 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - - 2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - use the `Analyzers.Add()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`// The index definition -public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string[] Tags { get; set; } - public string Content { get; set; } - } - - public BlogPosts_ByTagsAndContent() - { - Map = posts => from post in posts - select new IndexEntry() - { - Tags = post.Tags, - Content = post.Content - }; - - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - Analyzers.Add(x => x.Content, - typeof(SnowballAnalyzer).AssemblyQualifiedName); - } -} -`} - - - - -{`// The index definition -var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") -{ - Map = posts => from post in posts - select new {post.Tags, post.Content}, - - Analyzers = - { - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - {x => x.Tags, "SimpleAnalyzer"}, - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} - } -}.ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `FieldIndexing.Exact` - * `FieldIndexing.Search` - * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`public class BlogPosts_ByContent : AbstractIndexCreationTask -\{ - public BlogPosts_ByContent() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Search' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.Search); - - // => Index-field 'Content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `FieldIndexing.Exact`, - RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask -\{ - public Employees_ByFirstAndLastName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName, - FirstName = employee.FirstName - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Exact' on index-field 'FirstName' - Indexes.Add(x => x.FirstName, FieldIndexing.Exact); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstName : AbstractIndexCreationTask -\{ - public Employees_ByFirstName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName - \}; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`public class BlogPosts_ByTitle : AbstractIndexCreationTask -\{ - public BlogPosts_ByTitle() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.No' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.No); - - // Set 'FieldStorage.Yes' to store the original content of field 'Content' - // in the index - Stores.Add(x => x.Content, FieldStorage.Yes); - - // => No analyzer will process field 'Content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public class AnalyzerDefinition -\{ - // Name of the analyzer - public string Name \{ get; set; \} - - // C# source-code of the analyzer - public string Code \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`// Define the put analyzer operation: -var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition -\{ - // The name must be same as the analyzer's class name - Name = "MyAnalyzer", - - Code = @" - using System.IO; - using Lucene.Net.Analysis; - using Lucene.Net.Analysis.Standard; - - namespace MyAnalyzer - \{ - public class MyAnalyzer : Lucene.Net.Analysis.Analyzer - \{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - throw new CodeOmitted(); - \} - \} - \}" -\}); - -// Deploy the analyzer: -store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-6.2/indexes/_using-analyzers-nodejs.mdx deleted file mode 100644 index b120b39ea1..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-analyzers-nodejs.mdx +++ /dev/null @@ -1,655 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - -1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - -2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - set the `analyze()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content - })\`; - - // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer - this.analyze("tags", "SimpleAnalyzer"); - - // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer - this.analyze("content", "Raven.Sample.SnowballAnalyzer"); - } -} -`} - - - - -{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); -builder.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content -})\`; -builder.analyzersStrings["tags"] = "SimpleAnalyzer"; -builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; - -await store.maintenance - .send(new PutIndexesOperation( - builder.toIndexDefinition(store.conventions))); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `Exact` - * `Search` - * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Search' on index-field 'content' - this.index("content", "Search"); - - // => Index-field 'content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FirstName = employee.FirstName " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Exact' on index-field 'FirstName' - this.index("FirstName", "Exact"); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName" + - "\})"; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'No' on index-field 'content' - this.index("content", "No"); - - // Set 'Yes' to store the original content of field 'content' in the index - this.store("content", "Yes"); - - // => No analyzer will process field 'content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`const analyzerDefinition = \{ - name: "analyzerName", - code: "code" -\}; -`} - - - -| Parameter | Type | Description | -|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`const analyzerDefinition = \{ - name: "MyAnalyzer", - code: "using System.IO;\\n" + - "using Lucene.Net.Analysis;\\n" + - "using Lucene.Net.Analysis.Standard;\\n" + - "\\n" + - "namespace MyAnalyzer\\n" + - "\{\\n" + - " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + - " \{\\n" + - " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + - " \{\\n" + - " throw new CodeOmitted();\\n" + - " \}\\n" + - " \}\\n" + - "\}\\n" -\}; - -await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-6.2/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 30631bba09..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,550 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-6.2/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 2866006674..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,480 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-6.2/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 9bda34e83c..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-php.mdx b/versioned_docs/version-6.2/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index d57827b1a7..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,560 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-python.mdx b/versioned_docs/version-6.2/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index ffbfebfff6..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,512 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-6.2/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-6.2/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/versioned_docs/version-6.2/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/versioned_docs/version-6.2/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index f784c64ebd..0000000000 --- a/versioned_docs/version-6.2/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.2/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-6.2/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index bc0dfd5fef..0000000000 --- a/versioned_docs/version-6.2/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.2/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/versioned_docs/version-6.2/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.2/indexes/_what-are-indexes-php.mdx b/versioned_docs/version-6.2/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/versioned_docs/version-6.2/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.2/indexes/_what-are-indexes-python.mdx b/versioned_docs/version-6.2/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/versioned_docs/version-6.2/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-6.2/indexes/boosting.mdx b/versioned_docs/version-6.2/indexes/boosting.mdx index 1a4f9e8126..e7a5bb4fd1 100644 --- a/versioned_docs/version-6.2/indexes/boosting.mdx +++ b/versioned_docs/version-6.2/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/_boosting-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_boosting-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_boosting-java.mdx b/versioned_docs/version-6.2/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_boosting-java.mdx rename to versioned_docs/version-6.2/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_boosting-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_boosting-php.mdx b/versioned_docs/version-6.2/indexes/content/_boosting-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_boosting-php.mdx rename to versioned_docs/version-6.2/indexes/content/_boosting-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-6.2/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-6.2/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_extending-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-basics-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-metadata-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-metadata-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-metadata-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-metadata-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-metadata-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-metadata-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-metadata-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-metadata-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-metadata-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-metadata-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-metadata-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-metadata-php.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-metadata-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-metadata-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-metadata-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-metadata-python.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-metadata-python.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.2/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-6.2/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-spatial-data-php.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-spatial-data-php.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_indexing-spatial-data-python.mdx b/versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_indexing-spatial-data-python.mdx rename to versioned_docs/version-6.2/indexes/content/_indexing-spatial-data-python.mdx diff --git a/versioned_docs/version-6.2/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-indexes-php.mdx b/versioned_docs/version-6.2/indexes/content/_map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-indexes-php.mdx rename to versioned_docs/version-6.2/indexes/content/_map-indexes-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-indexes-python.mdx b/versioned_docs/version-6.2/indexes/content/_map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-indexes-python.mdx rename to versioned_docs/version-6.2/indexes/content/_map-indexes-python.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-reduce-indexes-php.mdx b/versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-reduce-indexes-php.mdx rename to versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_map-reduce-indexes-python.mdx b/versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_map-reduce-indexes-python.mdx rename to versioned_docs/version-6.2/indexes/content/_map-reduce-indexes-python.mdx diff --git a/versioned_docs/version-6.2/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_multi-map-indexes-php.mdx b/versioned_docs/version-6.2/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_multi-map-indexes-php.mdx rename to versioned_docs/version-6.2/indexes/content/_multi-map-indexes-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_multi-map-indexes-python.mdx b/versioned_docs/version-6.2/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_multi-map-indexes-python.mdx rename to versioned_docs/version-6.2/indexes/content/_multi-map-indexes-python.mdx diff --git a/versioned_docs/version-6.2/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-6.2/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-6.2/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-6.2/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/_stale-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-6.2/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-csharp.mdx new file mode 100644 index 0000000000..08e46be32f --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-csharp.mdx @@ -0,0 +1,409 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB allows you to store data in a static index. + +* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), + without requiring the server to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + +* In this article: + * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) + * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) + * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) + * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) + + +## What content is stored in the index + +* A static index is defined by its map function which determines the content of each **index-entry**. + Typically, a single index-entry is created for each document from the indexed source collection - + unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. + +* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. + The content of an index-field can be a direct value from the source document field, + or a computed value based on the source document's content. + +* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). + The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. + +* **RavenDB allows you to store the original index-field value in the index**. + **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. + * The tokens (terms) generated by the analyzer are searchable but not stored. + * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) + (by default they are not stored). + +* This behavior is supported by both Lucene and Corax search engines. + + + +## When and why to store data in an index + +* **Store a field in the index if**: + + * **You want to project that field without loading the full document.** + Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. + If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. + * **The index-field is a computed value that you want to return in the query results.** + Normally, querying an index returns matching documents. + But if you're projecting a computed index-field that is Not stored, + you'll need to re-calculate the computed value manually from the documents returned by the query. + Storing the computed field avoids this extra step. + +* **You do not need to store a field in the index in order to**: + + * Filter by the field in a query. + * Perform full-text search on the field. + +* **Disadvantage of storing data in the index**: + + * Increased disk space usage - stored fields take up additional space and increase index size. + + + +## Storing data in index - from the Client API + +To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). +The default is `FieldStorage.No`. +**Index example:** + + + + +{`public class QuantityOrdered_ByCompany : + AbstractIndexCreationTask +{ + // The index-entry: + public class IndexEntry + { + // The index-fields: + public string Company { get; set; } + public string CompanyName { get; set; } + public int TotalItemsOrdered { get; set; } + } + + public QuantityOrdered_ByCompany() + { + Map = orders => from order in orders + select new IndexEntry + { + // 'Company' is a SIMPLE index-field, + // its value is taken directly from the Order document: + Company = order.Company, + + // 'CompanyName' is also considered a simple index-field, + // its value is taken from the related Company document: + CompanyName = LoadDocument(order.Company).Name, + + // 'TotalItemsOrdered' is a COMPUTED index-field: + // (the total quantity of items ordered in an Order document) + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }; + + // Store the calculated 'TotalItemsOrdered' index-field in the index: + // ================================================================== + Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); + + // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: + // ======================================================================================= + Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); + + // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): + // ============================================================================= + Stores.Add(x => x.CompanyName, FieldStorage.Yes); + } +} +`} + + + + +{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask +{ + public QuantityOrdered_ByCompany_JS() + { + Maps = new HashSet() + { + @"map('orders', function(order) { + let company = load(order.Company, 'Companies') + return { + Company: order.Company, + CompanyName: company.Name, + TotalItemsOrdered: order.Lines.reduce(function(total, line) { + return total + line.Quantity; + }, 0) + }; + })" + }; + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + }; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "QuantityOrdered/ByCompany", + + Maps = + { + @"from order in docs.Orders + select new + { + Company = order.Company, + CompanyName = LoadDocument(order.Company, ""Companies"").Name, + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }" + }, + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + } +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +**Querying the index and projecting results:** + + + +* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. + +* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. + The server does Not need to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class NumberOfItemsOrdered +{ + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select TotalItemsOrdered +`} + + + + + + + +* In this query, the projected results are defined by the custom class `ProjectedDetails`. + +* In this case, some of the fields in this class are Not stored in the index, so by default, + the server does need to load the original document from storage to complete the projection. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class ProjectedDetails +{ + // This field was Not stored in the index definition + public string Company { get; set; } + // This field was Not stored in the index definition + public DateTime OrderedAt { get; set; } + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select Company, OrderedAt, TotalItemsOrdered +`} + + + + + + + +## Storing data in index - from the Studio + +To configure index-fields from the Studio, open the _Edit Index_ view: + +![The index](../assets/store-field-in-index-1.png) + +1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). +2. These are the index-fields defined in the index map function. +Scroll down to configure each index-field: + +![Configure index fields](../assets/store-field-in-index-2.png) + +1. Open the _Fields_ tab. +2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. +3. Select _Yes_ from the dropdown to store the field in the index. +4. Here we configure index-field `CompanyName`. +5. This index-field is stored in the index and also configured for full-text search. +When querying the index from the Studio, +you can choose to display the stored index fields in the Results view: + +![Display the stored fields](../assets/store-field-in-index-3.png) + +1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). +2. Open the _Settings_ options. +3. Toggle ON _Show stored index fields only_. +4. When executing the query, + the results will display the stored index-fields for each object returned by the query. + + + + diff --git a/versioned_docs/version-6.2/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-6.2/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/_storing-data-in-index-php.mdx b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_storing-data-in-index-php.mdx rename to versioned_docs/version-6.2/indexes/content/_storing-data-in-index-php.mdx diff --git a/versioned_docs/version-6.2/indexes/_storing-data-in-index-python.mdx b/versioned_docs/version-6.2/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_storing-data-in-index-python.mdx rename to versioned_docs/version-6.2/indexes/content/_storing-data-in-index-python.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_using-analyzers-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_using-analyzers-csharp.mdx new file mode 100644 index 0000000000..ee633b3da5 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-analyzers-csharp.mdx @@ -0,0 +1,691 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + + 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + + 2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + use the `Analyzers.Add()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`// The index definition +public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string[] Tags { get; set; } + public string Content { get; set; } + } + + public BlogPosts_ByTagsAndContent() + { + Map = posts => from post in posts + select new IndexEntry() + { + Tags = post.Tags, + Content = post.Content + }; + + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + Analyzers.Add(x => x.Content, + typeof(SnowballAnalyzer).AssemblyQualifiedName); + } +} +`} + + + + +{`// The index definition +var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") +{ + Map = posts => from post in posts + select new {post.Tags, post.Content}, + + Analyzers = + { + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + {x => x.Tags, "SimpleAnalyzer"}, + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} + } +}.ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `FieldIndexing.Exact` + * `FieldIndexing.Search` + * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`public class BlogPosts_ByContent : AbstractIndexCreationTask +\{ + public BlogPosts_ByContent() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Search' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.Search); + + // => Index-field 'Content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `FieldIndexing.Exact`, + RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask +\{ + public Employees_ByFirstAndLastName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName, + FirstName = employee.FirstName + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Exact' on index-field 'FirstName' + Indexes.Add(x => x.FirstName, FieldIndexing.Exact); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstName : AbstractIndexCreationTask +\{ + public Employees_ByFirstName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName + \}; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`public class BlogPosts_ByTitle : AbstractIndexCreationTask +\{ + public BlogPosts_ByTitle() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.No' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.No); + + // Set 'FieldStorage.Yes' to store the original content of field 'Content' + // in the index + Stores.Add(x => x.Content, FieldStorage.Yes); + + // => No analyzer will process field 'Content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public class AnalyzerDefinition +\{ + // Name of the analyzer + public string Name \{ get; set; \} + + // C# source-code of the analyzer + public string Code \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`// Define the put analyzer operation: +var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition +\{ + // The name must be same as the analyzer's class name + Name = "MyAnalyzer", + + Code = @" + using System.IO; + using Lucene.Net.Analysis; + using Lucene.Net.Analysis.Standard; + + namespace MyAnalyzer + \{ + public class MyAnalyzer : Lucene.Net.Analysis.Analyzer + \{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + throw new CodeOmitted(); + \} + \} + \}" +\}); + +// Deploy the analyzer: +store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-6.2/indexes/_using-analyzers-java.mdx b/versioned_docs/version-6.2/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-6.2/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_using-analyzers-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_using-analyzers-nodejs.mdx new file mode 100644 index 0000000000..6d96e400e2 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-analyzers-nodejs.mdx @@ -0,0 +1,655 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + +1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + +2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + set the `analyze()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content + })\`; + + // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer + this.analyze("tags", "SimpleAnalyzer"); + + // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer + this.analyze("content", "Raven.Sample.SnowballAnalyzer"); + } +} +`} + + + + +{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); +builder.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content +})\`; +builder.analyzersStrings["tags"] = "SimpleAnalyzer"; +builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; + +await store.maintenance + .send(new PutIndexesOperation( + builder.toIndexDefinition(store.conventions))); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `Exact` + * `Search` + * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Search' on index-field 'content' + this.index("content", "Search"); + + // => Index-field 'content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FirstName = employee.FirstName " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Exact' on index-field 'FirstName' + this.index("FirstName", "Exact"); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName" + + "\})"; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'No' on index-field 'content' + this.index("content", "No"); + + // Set 'Yes' to store the original content of field 'content' in the index + this.store("content", "Yes"); + + // => No analyzer will process field 'content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`const analyzerDefinition = \{ + name: "analyzerName", + code: "code" +\}; +`} + + + +| Parameter | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`const analyzerDefinition = \{ + name: "MyAnalyzer", + code: "using System.IO;\\n" + + "using Lucene.Net.Analysis;\\n" + + "using Lucene.Net.Analysis.Standard;\\n" + + "\\n" + + "namespace MyAnalyzer\\n" + + "\{\\n" + + " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + + " \{\\n" + + " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + + " \{\\n" + + " throw new CodeOmitted();\\n" + + " \}\\n" + + " \}\\n" + + "\}\\n" +\}; + +await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..8484315d55 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,550 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..0fd89b32ac --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,480 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..146a2f25c5 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-php.mdx b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..690dfe4bd2 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,560 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-python.mdx b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..274c90ba20 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,512 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_using-term-vectors-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/versioned_docs/version-6.2/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-6.2/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-6.2/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-6.2/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-6.2/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/content/_what-are-indexes-csharp.mdx b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..947039be10 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_what-are-indexes-java.mdx b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..8c5adfb5e7 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_what-are-indexes-nodejs.mdx b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_what-are-indexes-php.mdx b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.2/indexes/content/_what-are-indexes-python.mdx b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/versioned_docs/version-6.2/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-6.2/indexes/creating-and-deploying.mdx b/versioned_docs/version-6.2/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/versioned_docs/version-6.2/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-6.2/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/extending-indexes.mdx b/versioned_docs/version-6.2/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-6.2/indexes/extending-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-basics.mdx b/versioned_docs/version-6.2/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-6.2/indexes/indexing-basics.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-6.2/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-6.2/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-6.2/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/versioned_docs/version-6.2/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-6.2/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-6.2/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-metadata.mdx b/versioned_docs/version-6.2/indexes/indexing-metadata.mdx index 6c81cc4ad3..9af5ee1d1d 100644 --- a/versioned_docs/version-6.2/indexes/indexing-metadata.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingMetadataCsharp from './_indexing-metadata-csharp.mdx'; -import IndexingMetadataJava from './_indexing-metadata-java.mdx'; -import IndexingMetadataPython from './_indexing-metadata-python.mdx'; -import IndexingMetadataPhp from './_indexing-metadata-php.mdx'; -import IndexingMetadataNodejs from './_indexing-metadata-nodejs.mdx'; +import IndexingMetadataCsharp from './content/_indexing-metadata-csharp.mdx'; +import IndexingMetadataJava from './content/_indexing-metadata-java.mdx'; +import IndexingMetadataPython from './content/_indexing-metadata-python.mdx'; +import IndexingMetadataPhp from './content/_indexing-metadata-php.mdx'; +import IndexingMetadataNodejs from './content/_indexing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-nested-data.mdx b/versioned_docs/version-6.2/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/versioned_docs/version-6.2/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-6.2/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/versioned_docs/version-6.2/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-related-documents.mdx b/versioned_docs/version-6.2/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/versioned_docs/version-6.2/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/indexing-spatial-data.mdx b/versioned_docs/version-6.2/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/versioned_docs/version-6.2/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-6.2/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/javascript-indexes.mdx b/versioned_docs/version-6.2/indexes/javascript-indexes.mdx index c3823fd587..d5a516c218 100644 --- a/versioned_docs/version-6.2/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-6.2/indexes/map-indexes.mdx b/versioned_docs/version-6.2/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/versioned_docs/version-6.2/indexes/map-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/map-reduce-indexes.mdx b/versioned_docs/version-6.2/indexes/map-reduce-indexes.mdx index b783b56532..eb29118146 100644 --- a/versioned_docs/version-6.2/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/multi-map-indexes.mdx b/versioned_docs/version-6.2/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/versioned_docs/version-6.2/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/number-type-conversion.mdx b/versioned_docs/version-6.2/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-6.2/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-6.2/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21157296fd..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1052 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-6.2/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-6.2/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_faceted-search-php.mdx b/versioned_docs/version-6.2/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_faceted-search-python.mdx b/versioned_docs/version-6.2/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 7bba94c71c..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,783 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_paging-java.mdx b/versioned_docs/version-6.2/indexes/querying/_paging-java.mdx deleted file mode 100644 index c69b33f0d7..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,307 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 253f2a5e98..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance -**Better performance**: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -**Performance hints**: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_paging-php.mdx b/versioned_docs/version-6.2/indexes/querying/_paging-php.mdx deleted file mode 100644 index 596a8e12fd..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,688 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_paging-python.mdx b/versioned_docs/version-6.2/indexes/querying/_paging-python.mdx deleted file mode 100644 index 3ca064b801..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,431 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_spatial-java.mdx b/versioned_docs/version-6.2/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_suggestions-php.mdx b/versioned_docs/version-6.2/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_suggestions-python.mdx b/versioned_docs/version-6.2/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/versioned_docs/version-6.2/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/versioned_docs/version-6.2/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_distinct-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_exploration-queries-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_exploration-queries-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_exploration-queries-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_exploration-queries-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_exploration-queries-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_exploration-queries-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_exploration-queries-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..7adddea4b9 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1052 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_filtering-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_filtering-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_filtering-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_filtering-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_filtering-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_highlighting-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_highlighting-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_highlighting-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_highlighting-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_highlighting-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_highlighting-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_include-explanations-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_include-explanations-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_include-explanations-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_include-explanations-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_intersection-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_intersection-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_intersection-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_intersection-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_intersection-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_intersection-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_intersection-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_morelikethis-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_morelikethis-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_morelikethis-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_morelikethis-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_morelikethis-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_morelikethis-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..8f8b1df9c8 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,783 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..0e9fbc3606 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,307 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..8f97f74d19 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance +**Better performance**: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +**Performance hints**: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_paging-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..9a3a910996 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,688 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_paging-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..a357c96094 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,431 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_projections-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_projections-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_projections-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_projections-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_projections-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_projections-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_projections-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_projections-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_projections-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_projections-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_query-index-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_query-index-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_query-index-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_query-index-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_query-index-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_query-index-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_query-index-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_searching-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_searching-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_searching-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_searching-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_searching-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_searching-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_searching-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_searching-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_searching-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_searching-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_sorting-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_sorting-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_sorting-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_sorting-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_sorting-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_sorting-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_sorting-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-6.2/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_spatial-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_spatial-php.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_spatial-php.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/_spatial-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_spatial-python.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_spatial-python.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-6.2/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-6.2/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-6.2/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_suggestions-php.mdx b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/content/_suggestions-python.mdx b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/versioned_docs/version-6.2/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/versioned_docs/version-6.2/indexes/querying/distinct.mdx b/versioned_docs/version-6.2/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-6.2/indexes/querying/distinct.mdx +++ b/versioned_docs/version-6.2/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/exploration-queries.mdx b/versioned_docs/version-6.2/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/versioned_docs/version-6.2/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-6.2/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/faceted-search.mdx b/versioned_docs/version-6.2/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/versioned_docs/version-6.2/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-6.2/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/filtering.mdx b/versioned_docs/version-6.2/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/versioned_docs/version-6.2/indexes/querying/filtering.mdx +++ b/versioned_docs/version-6.2/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/highlighting.mdx b/versioned_docs/version-6.2/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/versioned_docs/version-6.2/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-6.2/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/include-explanations.mdx b/versioned_docs/version-6.2/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/versioned_docs/version-6.2/indexes/querying/include-explanations.mdx +++ b/versioned_docs/version-6.2/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/intersection.mdx b/versioned_docs/version-6.2/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/versioned_docs/version-6.2/indexes/querying/intersection.mdx +++ b/versioned_docs/version-6.2/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/morelikethis.mdx b/versioned_docs/version-6.2/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/versioned_docs/version-6.2/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-6.2/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/paging.mdx b/versioned_docs/version-6.2/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/versioned_docs/version-6.2/indexes/querying/paging.mdx +++ b/versioned_docs/version-6.2/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/projections.mdx b/versioned_docs/version-6.2/indexes/querying/projections.mdx index 6a24194fc0..779a07b48b 100644 --- a/versioned_docs/version-6.2/indexes/querying/projections.mdx +++ b/versioned_docs/version-6.2/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/query-index.mdx b/versioned_docs/version-6.2/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/versioned_docs/version-6.2/indexes/querying/query-index.mdx +++ b/versioned_docs/version-6.2/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/searching.mdx b/versioned_docs/version-6.2/indexes/querying/searching.mdx index 9f0b5aebc1..9b88c79e82 100644 --- a/versioned_docs/version-6.2/indexes/querying/searching.mdx +++ b/versioned_docs/version-6.2/indexes/querying/searching.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/sorting.mdx b/versioned_docs/version-6.2/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/versioned_docs/version-6.2/indexes/querying/sorting.mdx +++ b/versioned_docs/version-6.2/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/spatial.mdx b/versioned_docs/version-6.2/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/versioned_docs/version-6.2/indexes/querying/spatial.mdx +++ b/versioned_docs/version-6.2/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-6.2/indexes/querying/suggestions.mdx b/versioned_docs/version-6.2/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/versioned_docs/version-6.2/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-6.2/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/sorting-and-collation.mdx b/versioned_docs/version-6.2/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-6.2/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-6.2/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-6.2/indexes/stale-indexes.mdx b/versioned_docs/version-6.2/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-6.2/indexes/stale-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/storing-data-in-index.mdx b/versioned_docs/version-6.2/indexes/storing-data-in-index.mdx index d14d9b3662..9fa4d96090 100644 --- a/versioned_docs/version-6.2/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-6.2/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "python", "php", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; diff --git a/versioned_docs/version-6.2/indexes/using-analyzers.mdx b/versioned_docs/version-6.2/indexes/using-analyzers.mdx index ff0865eb70..cfaf304f2e 100644 --- a/versioned_docs/version-6.2/indexes/using-analyzers.mdx +++ b/versioned_docs/version-6.2/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/using-dynamic-fields.mdx b/versioned_docs/version-6.2/indexes/using-dynamic-fields.mdx index 010c89de9b..fe92642e46 100644 --- a/versioned_docs/version-6.2/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-6.2/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/indexes/using-term-vectors.mdx b/versioned_docs/version-6.2/indexes/using-term-vectors.mdx index 94ef7ada0b..819e006fd0 100644 --- a/versioned_docs/version-6.2/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-6.2/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/versioned_docs/version-6.2/indexes/what-are-indexes.mdx b/versioned_docs/version-6.2/indexes/what-are-indexes.mdx index b05d8422dc..8821d797d4 100644 --- a/versioned_docs/version-6.2/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-6.2/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/server/_embedded-csharp.mdx b/versioned_docs/version-6.2/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/server/_embedded-csharp.mdx rename to versioned_docs/version-6.2/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-6.2/server/_embedded-java.mdx b/versioned_docs/version-6.2/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-6.2/server/_embedded-java.mdx rename to versioned_docs/version-6.2/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-6.2/server/embedded.mdx b/versioned_docs/version-6.2/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/versioned_docs/version-6.2/server/embedded.mdx +++ b/versioned_docs/version-6.2/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-6.2/server/extensions/_refresh-csharp.mdx b/versioned_docs/version-6.2/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/versioned_docs/version-6.2/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-6.2/server/extensions/_refresh-nodejs.mdx b/versioned_docs/version-6.2/server/extensions/_refresh-nodejs.mdx deleted file mode 100644 index f8a0a3d28c..0000000000 --- a/versioned_docs/version-6.2/server/extensions/_refresh-nodejs.mdx +++ /dev/null @@ -1,137 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - -## Overview - -To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. -This indicates when the document should be refreshed. - -This will cause the document to refresh **_only once_**! The refresh operation removes -the `@refresh` flag. - -The exact time that the document refreshes is not determined by the value of `@refresh` -- rather, the server refreshes documents at regular intervals determined by the Refresh -Configuration. The default interval is 60 seconds. - -Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) -to increment the same way it would after any other kind of update to the document. -This triggers any features that react to documents updating, including but not limited -to: - -* The document is re-indexed by any indexes that cover it. -* [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. -* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. - - - -## Examples - -#### Setting the refresh configuration for a database: - -To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. - - - -{`// Enable document refreshing and set the refresh interval to 5 minutes: -// ===================================================================== - -// Define the refresh configuration object -const refreshConfiguration = \{ - disabled: false, // Enable refreshing - refreshFrequencyInSec: 300 // Set interval to 5 minutes -\}; - -// Define the configure refresh operation, pass the configuration to set -const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); - -// Execute the operation by passing it to maintenance.send -await documentStore.maintenance.send(configureRefreshOp); -`} - - -#### Set a document to refresh 1 hour from now: - - - -{`// Setting a document to refresh after 1 hour: -// ==========================================+ - -// Load a document -const session = documentStore.openSession(); -const employee = await session.load("employees/1-A"); - -// Get the metadata of the document -const metadata = session.advanced.getMetadataFor(employee); - -// Set the "@refresh" metadata property with the refresh date in UTC format -const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) -metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); - -// Save the document -await session.saveChanges(); -`} - - - - - -## Syntax - - - -{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); -`} - - - -[//]: # (| Parameter | Type | Description |) -[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) -[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) -[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) -[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) - - - -{`// The refreshConfiguration object -\{ - disabled, - refreshFrequencyInSec -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| -| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | -| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-6.2/server/extensions/_expiration-csharp.mdx b/versioned_docs/version-6.2/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/server/extensions/_expiration-csharp.mdx rename to versioned_docs/version-6.2/server/extensions/content/_expiration-csharp.mdx diff --git a/versioned_docs/version-6.2/server/extensions/_expiration-nodejs.mdx b/versioned_docs/version-6.2/server/extensions/content/_expiration-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/server/extensions/_expiration-nodejs.mdx rename to versioned_docs/version-6.2/server/extensions/content/_expiration-nodejs.mdx diff --git a/versioned_docs/version-6.2/server/extensions/content/_refresh-csharp.mdx b/versioned_docs/version-6.2/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/versioned_docs/version-6.2/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-6.2/server/extensions/content/_refresh-nodejs.mdx b/versioned_docs/version-6.2/server/extensions/content/_refresh-nodejs.mdx new file mode 100644 index 0000000000..a4e68e0f7e --- /dev/null +++ b/versioned_docs/version-6.2/server/extensions/content/_refresh-nodejs.mdx @@ -0,0 +1,137 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + +## Overview + +To refresh a document, add a `@refresh` flag to the document's metadata specifying datetime in UTC format. +This indicates when the document should be refreshed. + +This will cause the document to refresh **_only once_**! The refresh operation removes +the `@refresh` flag. + +The exact time that the document refreshes is not determined by the value of `@refresh` +- rather, the server refreshes documents at regular intervals determined by the Refresh +Configuration. The default interval is 60 seconds. + +Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) +to increment the same way it would after any other kind of update to the document. +This triggers any features that react to documents updating, including but not limited +to: + +* The document is re-indexed by any indexes that cover it. +* [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) are triggered. +* A [revision](../../document-extensions/revisions/overview.mdx) of the document is created. + + + +## Examples + +#### Setting the refresh configuration for a database: + +To activate and/or configure document refreshing, the server needs to be sent a configuration object using the `ConfigureRefreshOperation` operation. + + + +{`// Enable document refreshing and set the refresh interval to 5 minutes: +// ===================================================================== + +// Define the refresh configuration object +const refreshConfiguration = \{ + disabled: false, // Enable refreshing + refreshFrequencyInSec: 300 // Set interval to 5 minutes +\}; + +// Define the configure refresh operation, pass the configuration to set +const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); + +// Execute the operation by passing it to maintenance.send +await documentStore.maintenance.send(configureRefreshOp); +`} + + +#### Set a document to refresh 1 hour from now: + + + +{`// Setting a document to refresh after 1 hour: +// ==========================================+ + +// Load a document +const session = documentStore.openSession(); +const employee = await session.load("employees/1-A"); + +// Get the metadata of the document +const metadata = session.advanced.getMetadataFor(employee); + +// Set the "@refresh" metadata property with the refresh date in UTC format +const refreshAt = new Date(new Date().getTime() + (60_000 * 60)) +metadata[CONSTANTS.Documents.Metadata.REFRESH] = refreshAt.toISOString(); + +// Save the document +await session.saveChanges(); +`} + + + + + +## Syntax + + + +{`const configureRefreshOp = new ConfigureRefreshOperation(refreshConfiguration); +`} + + + +[//]: # (| Parameter | Type | Description |) +[//]: # (|---------------------------|----------|-----------------------------------------------------------------------------------------------|) +[//]: # (| **configuration** | `object` | Refresh configuration that will be set on the server (for the database) |) +[//]: # (| **disabled** | `object` | If set to true, document refreshing is disabled for the entire database. Default: `true` |) +[//]: # (| **refreshFrequencyInSec** | `number` | Determines how often the server checks for documents that need to be refreshed. Default: `60` |) + + + +{`// The refreshConfiguration object +\{ + disabled, + refreshFrequencyInSec +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------| +| **disabled** | `boolean` | `true` - document refreshing is disabled for the entire database (Default).
`false` - document refreshing is enabled. | +| **refreshFrequencyInSec** | `number` | Set how often the server checks for documents that need to be refreshed.
Default: `60` | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-6.2/server/extensions/expiration.mdx b/versioned_docs/version-6.2/server/extensions/expiration.mdx index 3986525bb8..791e4136d6 100644 --- a/versioned_docs/version-6.2/server/extensions/expiration.mdx +++ b/versioned_docs/version-6.2/server/extensions/expiration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; -import ExpirationNodejs from './_expiration-nodejs.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; +import ExpirationNodejs from './content/_expiration-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/server/extensions/refresh.mdx b/versioned_docs/version-6.2/server/extensions/refresh.mdx index 8820271cfb..08eefe0c4f 100644 --- a/versioned_docs/version-6.2/server/extensions/refresh.mdx +++ b/versioned_docs/version-6.2/server/extensions/refresh.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; -import RefreshNodejs from './_refresh-nodejs.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; +import RefreshNodejs from './content/_refresh-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx b/versioned_docs/version-6.2/server/kb/content/_document-identifier-generation-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx rename to versioned_docs/version-6.2/server/kb/content/_document-identifier-generation-csharp.mdx diff --git a/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx b/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx index 6bec153835..46a987ed21 100644 --- a/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx +++ b/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; +import DocumentIDsCsharp from './content/_document-identifier-generation-csharp.mdx'; diff --git a/versioned_docs/version-6.2/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-6.2/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-6.2/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-6.2/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-6.2/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-6.2/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-6.2/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-6.2/server/storage/documents-compression.mdx b/versioned_docs/version-6.2/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-6.2/server/storage/documents-compression.mdx +++ b/versioned_docs/version-6.2/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/start/_test-driver-csharp.mdx b/versioned_docs/version-6.2/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-6.2/start/_test-driver-csharp.mdx rename to versioned_docs/version-6.2/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-6.2/start/_test-driver-java.mdx b/versioned_docs/version-6.2/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-6.2/start/_test-driver-java.mdx rename to versioned_docs/version-6.2/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-csharp.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-nodejs.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/versioned_docs/version-6.2/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/_overview-csharp.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/versioned_docs/version-6.2/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/_overview-nodejs.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index e9abea53ff..0000000000 --- a/versioned_docs/version-6.2/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-csharp.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/versioned_docs/version-6.2/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-csharp.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-nodejs.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..a6bf58b4c8 --- /dev/null +++ b/versioned_docs/version-6.2/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/existing-project.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/versioned_docs/version-6.2/start/guides/azure-functions/existing-project.mdx +++ b/versioned_docs/version-6.2/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/start/guides/azure-functions/overview.mdx b/versioned_docs/version-6.2/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/versioned_docs/version-6.2/start/guides/azure-functions/overview.mdx +++ b/versioned_docs/version-6.2/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-6.2/start/test-driver.mdx b/versioned_docs/version-6.2/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/versioned_docs/version-6.2/start/test-driver.mdx +++ b/versioned_docs/version-6.2/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/azure-open-ai.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/azure-open-ai.mdx index 92beddd22a..1d9b74dc89 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/azure-open-ai.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/azure-open-ai.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AzureOpenAiCsharp from './_azure-open-ai-csharp.mdx'; +import AzureOpenAiCsharp from './content/_azure-open-ai-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_azure-open-ai-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_azure-open-ai-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_azure-open-ai-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_azure-open-ai-csharp.mdx index bb93f97dcf..777fb9f1f1 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_azure-open-ai-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_azure-open-ai-csharp.mdx @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to azure open ai](./assets/azure-open-ai.png) +![connection string to azure open ai](../assets/azure-open-ai.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_embedded-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_embedded-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_embedded-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_embedded-csharp.mdx index d5828b86e0..476cb2d61a 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_embedded-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_embedded-csharp.mdx @@ -20,7 +20,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to the embedded model](./assets/embedded.png) +![connection string to the embedded model](../assets/embedded.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_google-ai-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_google-ai-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_google-ai-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_google-ai-csharp.mdx index 4143c34fad..36a2106a11 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_google-ai-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_google-ai-csharp.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to google ai](./assets/google-ai.png) +![connection string to google ai](../assets/google-ai.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_hugging-face-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_hugging-face-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_hugging-face-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_hugging-face-csharp.mdx index d787a528d7..2488fea938 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_hugging-face-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_hugging-face-csharp.mdx @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to hugging face](./assets/hugging-face.png) +![connection string to hugging face](../assets/hugging-face.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_mistral-ai-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_mistral-ai-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_mistral-ai-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_mistral-ai-csharp.mdx index 773642af8e..7de511fd74 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_mistral-ai-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_mistral-ai-csharp.mdx @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to mistral ai](./assets/mistral-ai.png) +![connection string to mistral ai](../assets/mistral-ai.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_ollama-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_ollama-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_ollama-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_ollama-csharp.mdx index 37f6c4771f..8a5fc5bc03 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_ollama-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_ollama-csharp.mdx @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to ollama](./assets/ollama.png) +![connection string to ollama](../assets/ollama.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/_open-ai-csharp.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_open-ai-csharp.mdx similarity index 99% rename from versioned_docs/version-7.0/ai-integration/connection-strings/_open-ai-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/connection-strings/content/_open-ai-csharp.mdx index b2bb5fb9a9..1ed5d50d23 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/_open-ai-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/content/_open-ai-csharp.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Define the connection string - from the Studio -![connection string to open ai](./assets/open-ai.png) +![connection string to open ai](../assets/open-ai.png) 1. **Name** Enter a name for this connection string. diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/embedded.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/embedded.mdx index 598ce0fa66..d617c6dd4e 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/embedded.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/embedded.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/google-ai.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/google-ai.mdx index 6944c642ec..5d4f08b016 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/google-ai.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/google-ai.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GoogleAiCsharp from './_google-ai-csharp.mdx'; +import GoogleAiCsharp from './content/_google-ai-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/hugging-face.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/hugging-face.mdx index 0106b3cf91..f4ff8129f4 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/hugging-face.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/hugging-face.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HuggingFaceCsharp from './_hugging-face-csharp.mdx'; +import HuggingFaceCsharp from './content/_hugging-face-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/mistral-ai.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/mistral-ai.mdx index a29787f56c..097aa37f48 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/mistral-ai.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/mistral-ai.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MistralAiCsharp from './_mistral-ai-csharp.mdx'; +import MistralAiCsharp from './content/_mistral-ai-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/ollama.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/ollama.mdx index 98dc00aaa7..2919f3481d 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/ollama.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/ollama.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OllamaCsharp from './_ollama-csharp.mdx'; +import OllamaCsharp from './content/_ollama-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/connection-strings/open-ai.mdx b/versioned_docs/version-7.0/ai-integration/connection-strings/open-ai.mdx index 0ac496725e..e5a572981a 100644 --- a/versioned_docs/version-7.0/ai-integration/connection-strings/open-ai.mdx +++ b/versioned_docs/version-7.0/ai-integration/connection-strings/open-ai.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpenAiCsharp from './_open-ai-csharp.mdx'; +import OpenAiCsharp from './content/_open-ai-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/generating-embeddings/_embeddings-generation-task-csharp.mdx b/versioned_docs/version-7.0/ai-integration/generating-embeddings/content/_embeddings-generation-task-csharp.mdx similarity index 98% rename from versioned_docs/version-7.0/ai-integration/generating-embeddings/_embeddings-generation-task-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/generating-embeddings/content/_embeddings-generation-task-csharp.mdx index f1aa123cdd..2a7689369c 100644 --- a/versioned_docs/version-7.0/ai-integration/generating-embeddings/_embeddings-generation-task-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/generating-embeddings/content/_embeddings-generation-task-csharp.mdx @@ -26,7 +26,7 @@ import CodeBlock from '@theme/CodeBlock'; * **Define the general task settings**: - ![Create embeddings generation task - general](./assets/add-ai-task-3.png) + ![Create embeddings generation task - general](../assets/add-ai-task-3.png) 1. **Name** Enter a name for the task. @@ -67,7 +67,7 @@ import CodeBlock from '@theme/CodeBlock'; Click _Save_ to store the task definition or _Cancel_. * **Define the embeddings source - using PATHS**: - ![Create embeddings generation task - source by paths](./assets/add-ai-task-4.png) + ![Create embeddings generation task - source by paths](../assets/add-ai-task-4.png) 1. **Collection** Enter or select the source document collection from the dropdown. @@ -84,7 +84,7 @@ import CodeBlock from '@theme/CodeBlock'; Click to add the specified to the list. * **Define the embeddings source - using SCRIPT**: - ![Create embeddings generation task - source by script](./assets/add-ai-task-4-script.png) + ![Create embeddings generation task - source by script](../assets/add-ai-task-4-script.png) 1. **Embeddings source** Select `Script` to define the source content and chunking methods using a JavaScript script. @@ -98,7 +98,7 @@ import CodeBlock from '@theme/CodeBlock'; * **Define quantization and expiration - for the generated embeddings from the source documents**: - ![Create embeddings generation task - quantization and expiration](./assets/add-ai-task-5.png) + ![Create embeddings generation task - quantization and expiration](../assets/add-ai-task-5.png) 1. **Quantization** Select the quantization method that RavenDB will apply to embeddings received from the service provider. @@ -117,7 +117,7 @@ import CodeBlock from '@theme/CodeBlock'; * **Define chunking method & expiration - for the embedding generated from a search term in a vector search query**: - ![Create embeddings generation task - for the query](./assets/add-ai-task-6.png) + ![Create embeddings generation task - for the query](../assets/add-ai-task-6.png) 1. **Querying** This label indicates that this section configures parameters only for embeddings diff --git a/versioned_docs/version-7.0/ai-integration/generating-embeddings/embeddings-generation-task.mdx b/versioned_docs/version-7.0/ai-integration/generating-embeddings/embeddings-generation-task.mdx index 427c905b9f..a9d8d54862 100644 --- a/versioned_docs/version-7.0/ai-integration/generating-embeddings/embeddings-generation-task.mdx +++ b/versioned_docs/version-7.0/ai-integration/generating-embeddings/embeddings-generation-task.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddingsGenerationTaskCsharp from './_embeddings-generation-task-csharp.mdx'; +import EmbeddingsGenerationTaskCsharp from './content/_embeddings-generation-task-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/_data-types-for-vector-search-csharp.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/content/_data-types-for-vector-search-csharp.mdx similarity index 99% rename from versioned_docs/version-7.0/ai-integration/vector-search/_data-types-for-vector-search-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/vector-search/content/_data-types-for-vector-search-csharp.mdx index e846e95ee9..6f9090a6b2 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/_data-types-for-vector-search-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/content/_data-types-for-vector-search-csharp.mdx @@ -120,7 +120,7 @@ For example: -![json document](./assets/json-document.png) +![json document](../assets/json-document.png) diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/_indexing-attachments-for-vector-search-csharp.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/content/_indexing-attachments-for-vector-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/ai-integration/vector-search/_indexing-attachments-for-vector-search-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/vector-search/content/_indexing-attachments-for-vector-search-csharp.mdx diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-dynamic-query-csharp.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-dynamic-query-csharp.mdx similarity index 99% rename from versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-dynamic-query-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-dynamic-query-csharp.mdx index ed499008f0..be2488b97c 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-dynamic-query-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-dynamic-query-csharp.mdx @@ -301,11 +301,11 @@ where vector.search(embedding.text(Name), "italian food", 0.82, 20) * Executing the above query on the RavenDB sample data will create the following **auto-index**: `Auto/Products/ByVector.search(embedding.text(Name))` - ![Search for italian food 1](./assets/vector-search-1.png) + ![Search for italian food 1](../assets/vector-search-1.png) * Running the same query at a lower similarity level will return more results related to _"Italian food"_ but they may be less similar: - ![Search for italian food 2](./assets/vector-search-2.png) + ![Search for italian food 2](../assets/vector-search-2.png) ### Querying pre-made embeddings generated by tasks * The following example searches for Category documents where the _'Name'_ field is similar to the search term `"candy"`. @@ -895,15 +895,15 @@ The auto-index generated by running the above dynamic query is: You can **view the index-entries** of this auto-index in the Studio's query view: -![Query the auto index](./assets/view-auto-index-entries-1.png) +![Query the auto index](../assets/view-auto-index-entries-1.png) 1. Go to the Query view in the Studio 2. Query the index 3. Open the settings dialog: -![Open the settings dialog](./assets/view-auto-index-entries-2.png) +![Open the settings dialog](../assets/view-auto-index-entries-2.png) -![The index entries](./assets/view-auto-index-entries-3.png) +![The index entries](../assets/view-auto-index-entries-3.png) diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-static-index-csharp.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-static-index-csharp.mdx similarity index 99% rename from versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-static-index-csharp.mdx rename to versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-static-index-csharp.mdx index c2ea7d0cce..46c594218b 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/_vector-search-using-static-index-csharp.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/content/_vector-search-using-static-index-csharp.mdx @@ -1517,9 +1517,9 @@ Running the above example on RavenDB’s sample data returns the following docum ## Configure the vector field in the Studio - ![Add vector field](./assets/add-vector-field-1.png) + ![Add vector field](../assets/add-vector-field-1.png) - ![Customize vector field](./assets/add-vector-field-2.png) + ![Customize vector field](../assets/add-vector-field-2.png) 1. **Vector field name** Enter the name of the vector field to customize. diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/data-types-for-vector-search.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/data-types-for-vector-search.mdx index be3d4bf51d..250d8c71bb 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/data-types-for-vector-search.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/data-types-for-vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DataTypesForVectorSearchCsharp from './_data-types-for-vector-search-csharp.mdx'; +import DataTypesForVectorSearchCsharp from './content/_data-types-for-vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/indexing-attachments-for-vector-search.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/indexing-attachments-for-vector-search.mdx index e2b914b035..8ab66113b3 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/indexing-attachments-for-vector-search.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/indexing-attachments-for-vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingAttachmentsForVectorSearchCsharp from './_indexing-attachments-for-vector-search-csharp.mdx'; +import IndexingAttachmentsForVectorSearchCsharp from './content/_indexing-attachments-for-vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-dynamic-query.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-dynamic-query.mdx index fa442c9b34..a9ed2cfe71 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-dynamic-query.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-dynamic-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchUsingDynamicQueryCsharp from './_vector-search-using-dynamic-query-csharp.mdx'; +import VectorSearchUsingDynamicQueryCsharp from './content/_vector-search-using-dynamic-query-csharp.mdx'; diff --git a/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-static-index.mdx b/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-static-index.mdx index 4e859d94d0..42a799c240 100644 --- a/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-static-index.mdx +++ b/versioned_docs/version-7.0/ai-integration/vector-search/vector-search-using-static-index.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchUsingStaticIndexCsharp from './_vector-search-using-static-index-csharp.mdx'; +import VectorSearchUsingStaticIndexCsharp from './content/_vector-search-using-static-index-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-7.0/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-7.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-7.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-7.0/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-7.0/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-7.0/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-7.0/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-7.0/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-7.0/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-7.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-7.0/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-7.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-7.0/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-7.0/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-7.0/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-7.0/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-7.0/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-7.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-7.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-7.0/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx b/versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx rename to versioned_docs/version-7.0/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-7.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 668d999b7d..5c6923b919 100644 --- a/versioned_docs/version-7.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-7.0/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchNodejs from './_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchNodejs from './content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/commands/_overview-csharp.mdx b/versioned_docs/version-7.0/client-api/commands/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/_overview-csharp.mdx rename to versioned_docs/version-7.0/client-api/commands/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/_overview-java.mdx b/versioned_docs/version-7.0/client-api/commands/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/_overview-java.mdx rename to versioned_docs/version-7.0/client-api/commands/content/_overview-java.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/_overview-nodejs.mdx b/versioned_docs/version-7.0/client-api/commands/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/_overview-nodejs.mdx rename to versioned_docs/version-7.0/client-api/commands/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_delete-nodejs.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_delete-nodejs.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_delete-php.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_delete-php.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_delete-php.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_delete-python.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_delete-python.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_delete-python.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_get-php.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_get-php.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_get-php.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_get-python.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_get-python.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_get-python.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_put-nodejs.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_put-nodejs.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_put-php.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_put-php.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_put-php.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/_put-python.mdx b/versioned_docs/version-7.0/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/commands/documents/_put-python.mdx rename to versioned_docs/version-7.0/client-api/commands/documents/content/_put-python.mdx diff --git a/versioned_docs/version-7.0/client-api/commands/documents/delete.mdx b/versioned_docs/version-7.0/client-api/commands/documents/delete.mdx index 61091b815c..a88bb5f5db 100644 --- a/versioned_docs/version-7.0/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-7.0/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/commands/documents/get.mdx b/versioned_docs/version-7.0/client-api/commands/documents/get.mdx index 1e303a3f73..325076a4dc 100644 --- a/versioned_docs/version-7.0/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-7.0/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/commands/documents/put.mdx b/versioned_docs/version-7.0/client-api/commands/documents/put.mdx index ee9e70143c..9c8ba28480 100644 --- a/versioned_docs/version-7.0/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-7.0/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/commands/overview.mdx b/versioned_docs/version-7.0/client-api/commands/overview.mdx index dd0aca1a6c..744fb40071 100644 --- a/versioned_docs/version-7.0/client-api/commands/overview.mdx +++ b/versioned_docs/version-7.0/client-api/commands/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-7.0/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/conventions.mdx b/versioned_docs/version-7.0/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/versioned_docs/version-7.0/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/deserialization.mdx b/versioned_docs/version-7.0/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-7.0/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-7.0/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-7.0/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to versioned_docs/version-7.0/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/versioned_docs/version-7.0/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-7.0/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/versioned_docs/version-7.0/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/configuration/serialization.mdx b/versioned_docs/version-7.0/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-7.0/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-7.0/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-7.0/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/_creating-document-store-java.mdx b/versioned_docs/version-7.0/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-7.0/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-7.0/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-7.0/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-7.0/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-7.0/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-7.0/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-7.0/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-7.0/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-7.0/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-7.0/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-7.0/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/creating-document-store.mdx b/versioned_docs/version-7.0/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-7.0/client-api/creating-document-store.mdx +++ b/versioned_docs/version-7.0/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index cd09e4587d..0000000000 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index c2d1857b87..0000000000 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,134 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 12e6eedbd2..0000000000 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/concurrent-subscriptions.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_examples-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..30fd3f7254 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..aaa26a16f7 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,134 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..d82e45f68c --- /dev/null +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_examples-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to versioned_docs/version-7.0/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-7.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 881ea78195..16791e745a 100644 --- a/versioned_docs/version-7.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-7.0/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-7.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-7.0/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-7.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-7.0/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-7.0/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-7.0/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-7.0/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-7.0/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-7.0/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-7.0/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-nodejs.mdx b/versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to versioned_docs/version-7.0/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-7.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-7.0/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-7.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-7.0/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-7.0/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-7.0/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/versioned_docs/version-7.0/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-7.0/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-7.0/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-7.0/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-7.0/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/net-client-versions.mdx b/versioned_docs/version-7.0/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-7.0/client-api/net-client-versions.mdx +++ b/versioned_docs/version-7.0/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_delete-attachment-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_get-attachment-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_get-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/attachments/_put-attachment-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/attachments/content/_put-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/delete-attachment.mdx index b1b8dc0862..b4a5d42046 100644 --- a/versioned_docs/version-7.0/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-7.0/client-api/operations/attachments/delete-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; -import DeleteAttachmentNodejs from './_delete-attachment-nodejs.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; +import DeleteAttachmentNodejs from './content/_delete-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/get-attachment.mdx index dfbe7f67bf..16af9d26fc 100644 --- a/versioned_docs/version-7.0/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-7.0/client-api/operations/attachments/get-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; -import GetAttachmentNodejs from './_get-attachment-nodejs.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; +import GetAttachmentNodejs from './content/_get-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-7.0/client-api/operations/attachments/put-attachment.mdx index 7d63f1af0f..19a6aa8702 100644 --- a/versioned_docs/version-7.0/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-7.0/client-api/operations/attachments/put-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; -import PutAttachmentNodejs from './_put-attachment-nodejs.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; +import PutAttachmentNodejs from './content/_put-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-php.mdx b/versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-php.mdx rename to versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-python.mdx b/versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/common/_delete-by-query-python.mdx rename to versioned_docs/version-7.0/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-7.0/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/versioned_docs/version-7.0/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-7.0/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx index 9fa9b82577..6a464097cf 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeExpirationCsharp from './_compare-exchange-expiration-csharp.mdx'; +import CompareExchangeExpirationCsharp from './content/_compare-exchange-expiration-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx index e33c03af63..34f85441b1 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/compare-exchange-metadata.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeMetadataCsharp from './_compare-exchange-metadata-csharp.mdx'; +import CompareExchangeMetadataCsharp from './content/_compare-exchange-metadata-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_compare-exchange-expiration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_compare-exchange-expiration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_compare-exchange-metadata-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_compare-exchange-metadata-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-java.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_delete-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_delete-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-java.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-java.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_get-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_get-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_include-compare-exchange-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_include-compare-exchange-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_include-compare-exchange-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_include-compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-java.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-java.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-php.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-php.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-python.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_overview-python.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_overview-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-java.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/compare-exchange/_put-compare-exchange-value-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/compare-exchange/content/_put-compare-exchange-value-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx index 5cd2b2f3bb..4dbcb13cc5 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/delete-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeValueCsharp from './_delete-compare-exchange-value-csharp.mdx'; -import DeleteCompareExchangeValueJava from './_delete-compare-exchange-value-java.mdx'; -import DeleteCompareExchangeValueNodejs from './_delete-compare-exchange-value-nodejs.mdx'; +import DeleteCompareExchangeValueCsharp from './content/_delete-compare-exchange-value-csharp.mdx'; +import DeleteCompareExchangeValueJava from './content/_delete-compare-exchange-value-java.mdx'; +import DeleteCompareExchangeValueNodejs from './content/_delete-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx index 5a3faf4c6d..797adb1e32 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValueCsharp from './_get-compare-exchange-value-csharp.mdx'; -import GetCompareExchangeValueJava from './_get-compare-exchange-value-java.mdx'; -import GetCompareExchangeValueNodejs from './_get-compare-exchange-value-nodejs.mdx'; +import GetCompareExchangeValueCsharp from './content/_get-compare-exchange-value-csharp.mdx'; +import GetCompareExchangeValueJava from './content/_get-compare-exchange-value-java.mdx'; +import GetCompareExchangeValueNodejs from './content/_get-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx index 3cd524682d..7371593482 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/get-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCompareExchangeValuesCsharp from './_get-compare-exchange-values-csharp.mdx'; -import GetCompareExchangeValuesJava from './_get-compare-exchange-values-java.mdx'; -import GetCompareExchangeValuesNodejs from './_get-compare-exchange-values-nodejs.mdx'; +import GetCompareExchangeValuesCsharp from './content/_get-compare-exchange-values-csharp.mdx'; +import GetCompareExchangeValuesJava from './content/_get-compare-exchange-values-java.mdx'; +import GetCompareExchangeValuesNodejs from './content/_get-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/include-compare-exchange.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/include-compare-exchange.mdx index ef602a655c..c2da54868f 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/include-compare-exchange.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/include-compare-exchange.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeCompareExchangeCsharp from './_include-compare-exchange-csharp.mdx'; -import IncludeCompareExchangeNodejs from './_include-compare-exchange-nodejs.mdx'; +import IncludeCompareExchangeCsharp from './content/_include-compare-exchange-csharp.mdx'; +import IncludeCompareExchangeNodejs from './content/_include-compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/overview.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/overview.mdx index 66ee3a1273..d63e1a098c 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/overview.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "php"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx b/versioned_docs/version-7.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx index ed5ae625f9..fe51a43af8 100644 --- a/versioned_docs/version-7.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx +++ b/versioned_docs/version-7.0/client-api/operations/compare-exchange/put-compare-exchange-value.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeValueCsharp from './_put-compare-exchange-value-csharp.mdx'; -import PutCompareExchangeValueJava from './_put-compare-exchange-value-java.mdx'; -import PutCompareExchangeValueNodejs from './_put-compare-exchange-value-nodejs.mdx'; +import PutCompareExchangeValueCsharp from './content/_put-compare-exchange-value-csharp.mdx'; +import PutCompareExchangeValueJava from './content/_put-compare-exchange-value-java.mdx'; +import PutCompareExchangeValueNodejs from './content/_put-compare-exchange-value-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/_what-are-operations-php.mdx b/versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/_what-are-operations-php.mdx rename to versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/_what-are-operations-python.mdx b/versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/_what-are-operations-python.mdx rename to versioned_docs/version-7.0/client-api/operations/content/_what-are-operations-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-php.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_counter-batch-php.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_get-counters-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_get-counters-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/_get-counters-php.mdx b/versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/counters/_get-counters-php.mdx rename to versioned_docs/version-7.0/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-7.0/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/versioned_docs/version-7.0/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-7.0/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-7.0/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/versioned_docs/version-7.0/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-7.0/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to versioned_docs/version-7.0/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-7.0/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index 411e7a0097..0de1650d28 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 0c2b4eac5d..375985d7be 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 097f3eefc1..170c2de116 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/_get-stats-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/add-etl.mdx index e1ee997ddf..f4df4215da 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx index c6f08cb6ef..d06a2bfd07 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx index ecbdd10352..619c94b24d 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OngoingTaskOperationsCsharp from './_ongoing-task-operations-csharp.mdx'; +import OngoingTaskOperationsCsharp from './content/_ongoing-task-operations-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_set-based-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_set-based-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/_single-document-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/patching/_single-document-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/patching/set-based.mdx b/versioned_docs/version-7.0/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/versioned_docs/version-7.0/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-7.0/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/patching/single-document.mdx b/versioned_docs/version-7.0/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/versioned_docs/version-7.0/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-7.0/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-php.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-php.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-python.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_add-database-node-python.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-php.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-php.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-python.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_compact-database-python.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/create-database.mdx index 06626431e0..59effdb582 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 717fff9f05..0a89243169 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 40fd888f09..3cdddcb768 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-7.0/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/operations/what-are-operations.mdx b/versioned_docs/version-7.0/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/versioned_docs/version-7.0/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-7.0/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-7.0/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-7.0/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/security/deserialization-security.mdx b/versioned_docs/version-7.0/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-7.0/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-7.0/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx deleted file mode 100644 index 811678c09d..0000000000 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-csharp.mdx +++ /dev/null @@ -1,363 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - session.Store(new User(), "users/johndoe"); - session.SaveChanges(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var session1 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var session2 = store.OpenSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = session1.Load("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = session2.Load("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - session1.SaveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - session2.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session: - TransactionMode = TransactionMode.ClusterWide - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - await asyncSession.SaveChangesAsync(); - // An atomic guard is now automatically created for the new document "users/johndoe". -} - -// Open two concurrent cluster-wide sessions: -using (var asyncSession1 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -using (var asyncSession2 = store.OpenAsyncSession( - new SessionOptions - {TransactionMode = TransactionMode.ClusterWide})) -{ - // Both sessions load the same document: - var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); - loadedUser1.Name = "jindoe"; - - var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); - loadedUser2.Name = "jandoe"; - - // asyncSession1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - await asyncSession1.SaveChangesAsync(); - - // asyncSession2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - await asyncSession2.SaveChangesAsync(); -} -`} - - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - session.Store(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - TransactionMode = TransactionMode.ClusterWide, - // Disable atomic-guards - DisableAtomicDocumentWritesInClusterWideTransaction = true - })) -{ - await asyncSession.StoreAsync(new User(), "users/johndoe"); - - // No atomic-guard will be created upon saveChanges - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`Load` the document into the session before storing it** - - even if the document is expected to be new. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - - -{`using (var session = store.OpenSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating a new one or modifying if already exists - var user = session.Load("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - session.Store(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions - { - // Open a cluster-wide session - TransactionMode = TransactionMode.ClusterWide - })) -{ - // Load the user document BEFORE creating or updating - var user = await asyncSession.LoadAsync("users/johndoe"); - - if (user == null) - { - // Document doesn't exist => create a new document: - var newUser = new User - { - Name = "John Doe", - // ... initialize other properties - }; - - // Store the new user document in the session - await asyncSession.StoreAsync(newUser, "users/johndoe"); - } - else - { - // Document exists => apply your modifications: - user.Name = "New name"; - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - } - - // Commit your changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx deleted file mode 100644 index d9ae1ff263..0000000000 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-nodejs.mdx +++ /dev/null @@ -1,261 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`const user = \{ - firstName: "John", - lastName: "Doe" -\}; - -// Open a cluster-wide session: -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -await session.store(user, "users/johndoe"); -await session.saveChanges(); -// An atomic-guard is now automatically created for the new document "users/johndoe". - -// Open two concurrent cluster-wide sessions: -const session1 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); -const session2 = documentStore.openSession(\{ - transactionMode: "ClusterWide" -\}); - -// Both sessions load the same document: -const loadedUser1 = await session1.load("users/johndoe"); -loadedUser1.name = "jindoe"; - -const loadedUser2 = await session2.load("users/johndoe"); -loadedUser2.name = "jandoe"; - -// session1 saves its changes first — -// this increments the Raft index of the associated atomic guard. -await session1.saveChanges(); - -// session2 tries to save using an outdated atomic guard version -// and fails with a ConcurrencyException. -await session2.saveChanges(); -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`// Open a cluster-wide session -const session = documentStore.openSession(\{ - transactionMode: "ClusterWide", - // Disable atomic-guards - disableAtomicDocumentWritesInClusterWideTransaction: true -\}); - -await session.store(user, "users/johndoe"); - -// No atomic-guard will be created upon saveChanges -await session.saveChanges(); -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`const session = documentStore.openSession(\{ - // Open a cluster-wide session - transactionMode: "ClusterWide" -\}); - -// Load the user document BEFORE creating or updating -const user = await session.load("users/johndoe"); - -if (!user) \{ - // Document doesn't exist => create a new document - const newUser = \{ - name: "John Doe", - // ... initialize other properties - \}; - - // Store the new user document in the session - await session.store(newUser, "users/johndoe"); - -\} else \{ - // Document exists => apply your modifications - user.name = "New name"; - // ... make any other updates - - // No need to call store() again - // RavenDB tracks changes on loaded entities -\} - -// Commit your changes -await session.saveChanges(); -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx deleted file mode 100644 index aee89e6ab0..0000000000 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-php.mdx +++ /dev/null @@ -1,276 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`// Open a cluster-wide session: -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // An atomic-guard is now automatically created for the new document "users/johndoe". - $session->saveChanges(); -\} finally \{ - $session->close(); -\} - -// Open two concurrent cluster-wide sessions: - -$sessionOptions1 = new SessionOptions(); -$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); - -$session1 = $store->openSession($sessionOptions1); -try \{ - $sessionOptions2 = new SessionOptions(); - $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); - $session2 = $store->openSession($sessionOptions2); - - try \{ - // Both sessions load the same document: - var $loadedUser1 = $session1->load(User::class, "users/johndoe"); - $loadedUser1->setName("jindoe"); - - $loadedUser2 = $session2->load(User::class, "users/johndoe"); - $loadedUser2->setName("jandoe"); - - // session1 saves its changes first — - // this increments the Raft index of the associated atomic guard. - $session1->saveChanges(); - - // session2 tries to save using an outdated atomic guard version - // and fails with a ConcurrencyException. - $session2->saveChanges(); - \} finally \{ - $session2->close(); - \} - -\} finally \{ - $session1->close(); -\} -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); -$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); - -$session = $store->openSession($sessionOptions); - -try \{ - $session->store(new User(), "users/johndoe"); - // No atomic-guard will be created upon saveChanges - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`// Open a cluster-wide session -$sessionOptions = new SessionOptions(); -$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); - -$session = $store->openSession($sessionOptions); -try \{ - // Load the user document BEFORE creating or updating - $user = $session->load(User::class, "users/johndoe"); - - if ($user === null) \{ - // Document doesn't exist => create a new document: - $newUser = new User(); - $newUser->setName("John Doe"); - // ... initialize other properties - - // Store the new user document in the session - $session->store($newUser, "users/johndoe"); - \} else \{ - // Document exists => apply your modifications: - $user->setName("New name"); - // ... make any other updates - - // No need to call Store() again - // RavenDB tracks changes on loaded entities - \} - - // Commit your changes - $session->saveChanges(); -\} finally \{ - $session->close(); -\} -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx deleted file mode 100644 index e650aac9bf..0000000000 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_atomic-guards-python.mdx +++ /dev/null @@ -1,251 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) - that RavenDB creates and manages **automatically** to guarantee - [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. - -* Each document is associated with its own unique atomic guard item. - Atomic guards coordinate between sessions that attempt to write to the same document concurrently. - Saving a document will be prevented if another session has modified the document. - -* In this article: - * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) - * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) - * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) - * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) - * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) - * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) - - -## Atomic guard creation and update - - -Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. - -* **When creating a new document**: - A new atomic guard is created when a new document is successfully saved. - -* **When modifying an existing document that already has an atomic guard**: - * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. - This allows RavenDB to detect that the document has changed. - * If another session had loaded the document before the document's version changed, it will not be able to save its changes - unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. - -* **When modifying an existing document that doesn't have an atomic guard**: - * A new atomic guard is created when modifying an existing document that does not yet have one. - * The absence of the atomic guard may be because the document was created in a single-node session, - or because its atomic guard was manually removed (which is not recommended). - -* **When saving a document fails**: - * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. - * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. - - - -## Atomic guard usage example - -In the code sample below, an atomic guard is automatically created when a new document is saved. -It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, -only the first save succeeds, and the second fails with a _ConcurrencyException_. - - - -{`with store.open_session( - # Open a cluster-wide session: - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session: - session.store(User(), "users/johndoe") - session.save_changes() - # An atomic-guard is now automatically created for the new document "users/johndoe" - -# Open two concurrent cluster-wide sessions: -with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) -) as session1: - with store.open_session( - session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) - ) as session2: - # Both sessions load the same document: - loaded_user_1 = session1.load("users/johndoe", User) - loaded_user_1.name = "jindoe" - loaded_user_2 = session2.load("users/johndoe", User) - loaded_user_2.name = "jandoe" - - # session1 saves its changes first — - # this increments the Raft index of the associated atomic guard. - session1.save_changes() - - # session2 tries to save using an outdated atomic guard version - # and fails with a ConcurrencyException. - session2.save_changes() -`} - - -After running the above example, you can view the automatically created atomic guard in the Studio’s -[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): - -![Atomic Guard](./assets/atomic-guard.png) - -1. These are **custom compare-exchange items** that were manually created by you, - e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. - They are NOT the automatically created atomic guards. - -2. This is the **atomic guard** that was generated by running the example above. - - The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. - It is composed of: - * The prefix `rvn-atomic/`. - * The ID of the associated document. - - - * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. - * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. - - - - -## Atomic guard database scope - -* Atomic guards are local to the database on which they were defined. - -* Since atomic guards are implemented as compare-exchange items, - they are Not externally replicated to other databases by any ongoing replication task. - Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). - - - -## Disabling atomic guards - -* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries - to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. - -* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, - and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, - as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). - -* To disable the automatic creation and use of atomic guards in a cluster-wide session, - set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. - - - -{`with store.open_session( - # Open a cluster-wide session - session_options=SessionOptions( - transaction_mode=TransactionMode.CLUSTER_WIDE, - disable_atomic_document_writes_in_cluster_wide_transaction=True, - ) -) as session: - session.store(User(), "users/johndoe") - - # No atomic-guard will be created upon save_changes - session.save_changes() -`} - - - - - -## When are atomic guards removed - -Atomic guards are removed **automatically** in the following scenarios: -(you don't need to clean them up manually) - -* **Document deleted via a cluster-wide session**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Delete the document using a cluster wide session - its atomic guard will be removed automatically. - -* **Document expires via the expiration feature**: - * Create a document using a cluster wide session (an associated atomic guard is created). - * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). - * When the expiration time is reached, the document and its atomic guard will both be removed automatically. - * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, - it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. - You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. - - -* **Do not delete or modify atomic guards manually while they are in use by an active session**. - If a session attempts to save a document whose atomic guard has been removed or changed, - it will fail with an error. - -* If you accidentally remove an atomic guard that is associated with an existing document, - you can restore it by re-saving the document in a cluster-wide session, - this will re-create the atomic guard automatically. - - - - -## Best practice when storing a document in a cluster-wide transaction - -* When working with a cluster-wide session, - we recommend that you always **`load` the document into the session before storing it** - - even if the document is expected to be a new document. - -* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - - e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) - or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). - In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). - If you attempt to re-create such a document without loading it first, - RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. - ----- - -In this example, the document is loaded into the session BEFORE creating or modifying it: - - - -{`with store.open_session( - session_options=SessionOptions( - # Open a cluster-wide session - transaction_mode=TransactionMode.CLUSTER_WIDE - ) -) as session: - # Load the user document BEFORE creating or updating - user = session.load("users/johndoe", User) - - if user is None: - # Document doesn't exist => create a new document - new_user = User() - new_user.name = "John Doe" - # ... initialize other properties - - # Store the new user document in the session - session.store(new_user, "users/johndoe") - else: - # Document exists => apply your modifications - user.name = "New name" - # ... make any other updates - - # No need to call store() again - # RavenDB tracks changes on loaded entities - - # Commit your changes - session.save_changes() -`} - - - - - -When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: - -* **If the document is found**, it is loaded into the session, - and modifications will be saved successfully as long as no other session has modified the document in the meantime. - Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, - the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. - Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. - -* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): - * **If an atomic guard exists**, - the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. - * **If no atomic guard exists**, - the document is treated as a brand new document and will be saved as usual. - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/atomic-guards.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/atomic-guards.mdx index 8e705c3a32..29ace602dc 100644 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/atomic-guards.mdx +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/atomic-guards.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AtomicGuardsCsharp from './_atomic-guards-csharp.mdx'; -import AtomicGuardsPython from './_atomic-guards-python.mdx'; -import AtomicGuardsPhp from './_atomic-guards-php.mdx'; -import AtomicGuardsNodejs from './_atomic-guards-nodejs.mdx'; +import AtomicGuardsCsharp from './content/_atomic-guards-csharp.mdx'; +import AtomicGuardsPython from './content/_atomic-guards-python.mdx'; +import AtomicGuardsPhp from './content/_atomic-guards-php.mdx'; +import AtomicGuardsNodejs from './content/_atomic-guards-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/compare-exchange.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/compare-exchange.mdx index d4bdc9d5da..a98b9edf99 100644 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/compare-exchange.mdx +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/compare-exchange.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompareExchangeCsharp from './_compare-exchange-csharp.mdx'; -import CompareExchangePython from './_compare-exchange-python.mdx'; -import CompareExchangePhp from './_compare-exchange-php.mdx'; -import CompareExchangeNodejs from './_compare-exchange-nodejs.mdx'; +import CompareExchangeCsharp from './content/_compare-exchange-csharp.mdx'; +import CompareExchangePython from './content/_compare-exchange-python.mdx'; +import CompareExchangePhp from './content/_compare-exchange-php.mdx'; +import CompareExchangeNodejs from './content/_compare-exchange-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx new file mode 100644 index 0000000000..9c603424ba --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-csharp.mdx @@ -0,0 +1,363 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `SaveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + session.Store(new User(), "users/johndoe"); + session.SaveChanges(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var session1 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var session2 = store.OpenSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = session1.Load("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = session2.Load("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + session1.SaveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + session2.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session: + TransactionMode = TransactionMode.ClusterWide + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + await asyncSession.SaveChangesAsync(); + // An atomic guard is now automatically created for the new document "users/johndoe". +} + +// Open two concurrent cluster-wide sessions: +using (var asyncSession1 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +using (var asyncSession2 = store.OpenAsyncSession( + new SessionOptions + {TransactionMode = TransactionMode.ClusterWide})) +{ + // Both sessions load the same document: + var loadedUser1 = await asyncSession1.LoadAsync("users/johndoe"); + loadedUser1.Name = "jindoe"; + + var loadedUser2 = await asyncSession2.LoadAsync("users/johndoe"); + loadedUser2.Name = "jandoe"; + + // asyncSession1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + await asyncSession1.SaveChangesAsync(); + + // asyncSession2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + await asyncSession2.SaveChangesAsync(); +} +`} + + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + session.Store(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + TransactionMode = TransactionMode.ClusterWide, + // Disable atomic-guards + DisableAtomicDocumentWritesInClusterWideTransaction = true + })) +{ + await asyncSession.StoreAsync(new User(), "users/johndoe"); + + // No atomic-guard will be created upon saveChanges + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`Load` the document into the session before storing it** - + even if the document is expected to be new. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + as when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + + +{`using (var session = store.OpenSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating a new one or modifying if already exists + var user = session.Load("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + session.Store(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession(new SessionOptions + { + // Open a cluster-wide session + TransactionMode = TransactionMode.ClusterWide + })) +{ + // Load the user document BEFORE creating or updating + var user = await asyncSession.LoadAsync("users/johndoe"); + + if (user == null) + { + // Document doesn't exist => create a new document: + var newUser = new User + { + Name = "John Doe", + // ... initialize other properties + }; + + // Store the new user document in the session + await asyncSession.StoreAsync(newUser, "users/johndoe"); + } + else + { + // Document exists => apply your modifications: + user.Name = "New name"; + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + } + + // Commit your changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx new file mode 100644 index 0000000000..2825373609 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-nodejs.mdx @@ -0,0 +1,261 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`const user = \{ + firstName: "John", + lastName: "Doe" +\}; + +// Open a cluster-wide session: +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +await session.store(user, "users/johndoe"); +await session.saveChanges(); +// An atomic-guard is now automatically created for the new document "users/johndoe". + +// Open two concurrent cluster-wide sessions: +const session1 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); +const session2 = documentStore.openSession(\{ + transactionMode: "ClusterWide" +\}); + +// Both sessions load the same document: +const loadedUser1 = await session1.load("users/johndoe"); +loadedUser1.name = "jindoe"; + +const loadedUser2 = await session2.load("users/johndoe"); +loadedUser2.name = "jandoe"; + +// session1 saves its changes first — +// this increments the Raft index of the associated atomic guard. +await session1.saveChanges(); + +// session2 tries to save using an outdated atomic guard version +// and fails with a ConcurrencyException. +await session2.saveChanges(); +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`// Open a cluster-wide session +const session = documentStore.openSession(\{ + transactionMode: "ClusterWide", + // Disable atomic-guards + disableAtomicDocumentWritesInClusterWideTransaction: true +\}); + +await session.store(user, "users/johndoe"); + +// No atomic-guard will be created upon saveChanges +await session.saveChanges(); +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`const session = documentStore.openSession(\{ + // Open a cluster-wide session + transactionMode: "ClusterWide" +\}); + +// Load the user document BEFORE creating or updating +const user = await session.load("users/johndoe"); + +if (!user) \{ + // Document doesn't exist => create a new document + const newUser = \{ + name: "John Doe", + // ... initialize other properties + \}; + + // Store the new user document in the session + await session.store(newUser, "users/johndoe"); + +\} else \{ + // Document exists => apply your modifications + user.name = "New name"; + // ... make any other updates + + // No need to call store() again + // RavenDB tracks changes on loaded entities +\} + +// Commit your changes +await session.saveChanges(); +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx new file mode 100644 index 0000000000..c6fcf1e501 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-php.mdx @@ -0,0 +1,276 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [ClusterWide](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `saveChanges()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`// Open a cluster-wide session: +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // An atomic-guard is now automatically created for the new document "users/johndoe". + $session->saveChanges(); +\} finally \{ + $session->close(); +\} + +// Open two concurrent cluster-wide sessions: + +$sessionOptions1 = new SessionOptions(); +$sessionOptions1->setTransactionMode(TransactionMode::clusterWide()); + +$session1 = $store->openSession($sessionOptions1); +try \{ + $sessionOptions2 = new SessionOptions(); + $sessionOptions2->setTransactionMode(TransactionMode::clusterWide()); + $session2 = $store->openSession($sessionOptions2); + + try \{ + // Both sessions load the same document: + var $loadedUser1 = $session1->load(User::class, "users/johndoe"); + $loadedUser1->setName("jindoe"); + + $loadedUser2 = $session2->load(User::class, "users/johndoe"); + $loadedUser2->setName("jandoe"); + + // session1 saves its changes first — + // this increments the Raft index of the associated atomic guard. + $session1->saveChanges(); + + // session2 tries to save using an outdated atomic guard version + // and fails with a ConcurrencyException. + $session2->saveChanges(); + \} finally \{ + $session2->close(); + \} + +\} finally \{ + $session1->close(); +\} +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); +$sessionOptions->setDisableAtomicDocumentWritesInClusterWideTransaction(true); + +$session = $store->openSession($sessionOptions); + +try \{ + $session->store(new User(), "users/johndoe"); + // No atomic-guard will be created upon saveChanges + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`// Open a cluster-wide session +$sessionOptions = new SessionOptions(); +$sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + +$session = $store->openSession($sessionOptions); +try \{ + // Load the user document BEFORE creating or updating + $user = $session->load(User::class, "users/johndoe"); + + if ($user === null) \{ + // Document doesn't exist => create a new document: + $newUser = new User(); + $newUser->setName("John Doe"); + // ... initialize other properties + + // Store the new user document in the session + $session->store($newUser, "users/johndoe"); + \} else \{ + // Document exists => apply your modifications: + $user->setName("New name"); + // ... make any other updates + + // No need to call Store() again + // RavenDB tracks changes on loaded entities + \} + + // Commit your changes + $session->saveChanges(); +\} finally \{ + $session->close(); +\} +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx new file mode 100644 index 0000000000..489119ff63 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_atomic-guards-python.mdx @@ -0,0 +1,251 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Atomic Guards** are [compare-exchange key/value items](../../../client-api/operations/compare-exchange/overview.mdx) + that RavenDB creates and manages **automatically** to guarantee + [ACID](../../../server/clustering/cluster-transactions.mdx#cluster-transaction-properties) transactions in cluster-wide sessions. + +* Each document is associated with its own unique atomic guard item. + Atomic guards coordinate between sessions that attempt to write to the same document concurrently. + Saving a document will be prevented if another session has modified the document. + +* In this article: + * [Atomic guard creation and update](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-creation-and-update) + * [Atomic guard usage example](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-usage-example) + * [Atomic guard database scope](../../../client-api/session/cluster-transaction/atomic-guards.mdx#atomic-guard-database-scope) + * [Disabling atomic guards](../../../client-api/session/cluster-transaction/atomic-guards.mdx#disabling-atomic-guards) + * [When are atomic guards removed](../../../client-api/session/cluster-transaction/atomic-guards.mdx#when-are-atomic-guards-removed) + * [Best practice when storing a document in a cluster-wide transaction](../../../client-api/session/cluster-transaction/atomic-guards.mdx#best-practice-when-storing-a-document-in-a-cluster-wide-transaction) + + +## Atomic guard creation and update + + +Atomic guards are created and managed **only when the session's transaction mode is set to [CLUSTER_WIDE](../../../client-api/session/cluster-transaction/overview.mdx#open-a-cluster-transaction)**. + +* **When creating a new document**: + A new atomic guard is created when a new document is successfully saved. + +* **When modifying an existing document that already has an atomic guard**: + * The atomic guard’s Raft index is incremented when the document is successfully saved after being modified. + This allows RavenDB to detect that the document has changed. + * If another session had loaded the document before the document's version changed, it will not be able to save its changes + unless it first reloads the updated version. Otherwise, a `ConcurrencyException` is thrown. + +* **When modifying an existing document that doesn't have an atomic guard**: + * A new atomic guard is created when modifying an existing document that does not yet have one. + * The absence of the atomic guard may be because the document was created in a single-node session, + or because its atomic guard was manually removed (which is not recommended). + +* **When saving a document fails**: + * If a session's `save_changes()` fails, the entire session is rolled back and the atomic guard is Not created. + * Ensure your business logic is designed to re-execute the session in case saving changes fails for any reason. + + + +## Atomic guard usage example + +In the code sample below, an atomic guard is automatically created when a new document is saved. +It is then used to detect and prevent conflicting writes: when two sessions load and modify the same document, +only the first save succeeds, and the second fails with a _ConcurrencyException_. + + + +{`with store.open_session( + # Open a cluster-wide session: + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session: + session.store(User(), "users/johndoe") + session.save_changes() + # An atomic-guard is now automatically created for the new document "users/johndoe" + +# Open two concurrent cluster-wide sessions: +with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) +) as session1: + with store.open_session( + session_options=SessionOptions(transaction_mode=TransactionMode.CLUSTER_WIDE) + ) as session2: + # Both sessions load the same document: + loaded_user_1 = session1.load("users/johndoe", User) + loaded_user_1.name = "jindoe" + loaded_user_2 = session2.load("users/johndoe", User) + loaded_user_2.name = "jandoe" + + # session1 saves its changes first — + # this increments the Raft index of the associated atomic guard. + session1.save_changes() + + # session2 tries to save using an outdated atomic guard version + # and fails with a ConcurrencyException. + session2.save_changes() +`} + + +After running the above example, you can view the automatically created atomic guard in the Studio’s +[Compare-Exchange view](../../../studio/database/documents/compare-exchange-view.mdx#the-compare-exchange-view): + +![Atomic Guard](../assets/atomic-guard.png) + +1. These are **custom compare-exchange items** that were manually created by you, + e.g., via the [Put compare exchange operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value.mdx) - for any purpose you needed. + They are NOT the automatically created atomic guards. + +2. This is the **atomic guard** that was generated by running the example above. + + The generated atomic guard **key** is: `rvn-atomic/users/johndoe`. + It is composed of: + * The prefix `rvn-atomic/`. + * The ID of the associated document. + + + * Although this Studio view allows editing compare-exchange items, **do not delete or modify atomic guard entries**. + * Doing so will interfere with RavenDB's ability to track document versioning through atomic guards. + + + + +## Atomic guard database scope + +* Atomic guards are local to the database on which they were defined. + +* Since atomic guards are implemented as compare-exchange items, + they are Not externally replicated to other databases by any ongoing replication task. + Learn more in [why compare-exchange items are not replicated](../../../client-api/operations/compare-exchange/overview.mdx#why-compare-exchange-items-are-not-replicated-to-external-databases). + + + +## Disabling atomic guards + +* Before atomic guards were introduced (in RavenDB 5.2), client code had to explicitly manage compare-exchange entries + to ensure concurrency control and maintain ACID guarantees in cluster-wide transactions. + +* You can still take this manual approach by disabling the automatic use of atomic guards in a cluster-wide session, + and managing the required [compare-exchange key/value pairs](../../../client-api/operations/compare-exchange/overview.mdx) yourself, + as shown in this [example](../../../client-api/operations/compare-exchange/overview.mdx#example-i---email-address-reservation). + +* To disable the automatic creation and use of atomic guards in a cluster-wide session, + set the session's `DisableAtomicDocumentWritesInClusterWideTransaction` configuration option to `true`. + + + +{`with store.open_session( + # Open a cluster-wide session + session_options=SessionOptions( + transaction_mode=TransactionMode.CLUSTER_WIDE, + disable_atomic_document_writes_in_cluster_wide_transaction=True, + ) +) as session: + session.store(User(), "users/johndoe") + + # No atomic-guard will be created upon save_changes + session.save_changes() +`} + + + + + +## When are atomic guards removed + +Atomic guards are removed **automatically** in the following scenarios: +(you don't need to clean them up manually) + +* **Document deleted via a cluster-wide session**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Delete the document using a cluster wide session - its atomic guard will be removed automatically. + +* **Document expires via the expiration feature**: + * Create a document using a cluster wide session (an associated atomic guard is created). + * Add the `@expires` metadata property the document, as described in [Document expiration](../../../studio/database/settings/document-expiration.mdx). + * When the expiration time is reached, the document and its atomic guard will both be removed automatically. + * Since different cleanup tasks handle the removal of **expired** documents and the removal of their associated atomic guards, + it may happen that atomic guards of removed documents would linger in the compare exchange entries list a short while longer before they are removed. + You do Not need to remove such atomic guards yourself, they will be removed by the cleanup task. + + +* **Do not delete or modify atomic guards manually while they are in use by an active session**. + If a session attempts to save a document whose atomic guard has been removed or changed, + it will fail with an error. + +* If you accidentally remove an atomic guard that is associated with an existing document, + you can restore it by re-saving the document in a cluster-wide session, + this will re-create the atomic guard automatically. + + + + +## Best practice when storing a document in a cluster-wide transaction + +* When working with a cluster-wide session, + we recommend that you always **`load` the document into the session before storing it** - + even if the document is expected to be a new document. + +* This is especially important if a document (originally created in a cluster-wide transaction) was deleted **outside** of a cluster-wide session - + e.g., when using a [single-node session](../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction) + or the [DeleteByQueryOperation](../../../client-api/operations/common/delete-by-query.mdx). + In these cases, the document is deleted, but the atomic guard remains (it is not automatically removed). + If you attempt to re-create such a document without loading it first, + RavenDB will fail to save it because the session is unaware of the existing atomic guard’s latest Raft index. + +---- + +In this example, the document is loaded into the session BEFORE creating or modifying it: + + + +{`with store.open_session( + session_options=SessionOptions( + # Open a cluster-wide session + transaction_mode=TransactionMode.CLUSTER_WIDE + ) +) as session: + # Load the user document BEFORE creating or updating + user = session.load("users/johndoe", User) + + if user is None: + # Document doesn't exist => create a new document + new_user = User() + new_user.name = "John Doe" + # ... initialize other properties + + # Store the new user document in the session + session.store(new_user, "users/johndoe") + else: + # Document exists => apply your modifications + user.name = "New name" + # ... make any other updates + + # No need to call store() again + # RavenDB tracks changes on loaded entities + + # Commit your changes + session.save_changes() +`} + + + + + +When _loading_ a document in a cluster-wide session, RavenDB attempts to retrieve the document from the document store: + +* **If the document is found**, it is loaded into the session, + and modifications will be saved successfully as long as no other session has modified the document in the meantime. + Specifically, if the document’s [change vector](../../../server/clustering/replication/change-vector.mdx) matches the one currently stored on the server, + the save will proceed - after which the Raft index of the associated atomic guard will be incremented as expected. + Otherwise, RavenDB will fail the operation with a _ConcurrencyException_. + +* **If no document is found**, RavenDB will check whether a matching atomic guard exists (as in the case when the document was deleted outside of a cluster-wide session): + * **If an atomic guard exists**, + the client constructs a change vector for the document using the atomic guard’s Raft index, and the document will be saved with this change vector. + * **If no atomic guard exists**, + the document is treated as a brand new document and will be saved as usual. + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-php.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-php.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-python.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_compare-exchange-python.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_compare-exchange-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-php.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-php.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-python.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/cluster-transaction/_overview-python.mdx rename to versioned_docs/version-7.0/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-7.0/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/versioned_docs/version-7.0/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-7.0/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to versioned_docs/version-7.0/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-7.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/versioned_docs/version-7.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-7.0/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_deleting-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_deleting-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_deleting-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_deleting-entities-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_deleting-entities-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_deleting-entities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_loading-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_loading-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_loading-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_loading-entities-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_loading-entities-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_loading-entities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_opening-a-session-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_opening-a-session-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_opening-a-session-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_opening-a-session-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_opening-a-session-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_opening-a-session-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_saving-changes-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_saving-changes-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_saving-changes-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_saving-changes-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_saving-changes-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_saving-changes-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_storing-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_storing-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_storing-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_storing-entities-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_storing-entities-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_storing-entities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_updating-entities-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_updating-entities-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_updating-entities-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_updating-entities-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_updating-entities-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_updating-entities-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to versioned_docs/version-7.0/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/deleting-entities.mdx b/versioned_docs/version-7.0/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/versioned_docs/version-7.0/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-7.0/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-7.0/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-7.0/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-7.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-7.0/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-document-exists-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_clear-a-session-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_defer-operations-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-current-session-node-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-counters-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-php.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-php.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-python.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_refresh-entity-python.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-7.0/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-7.0/client-api/session/how-to/evict-entity-from-a-session.mdx index 958fc3efc6..b8527408ff 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/get-tracked-entities.mdx b/versioned_docs/version-7.0/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/get-tracked-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-7.0/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-7.0/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-7.0/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-7.0/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-7.0/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-7.0/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/loading-entities.mdx b/versioned_docs/version-7.0/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/versioned_docs/version-7.0/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/opening-a-session.mdx b/versioned_docs/version-7.0/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/versioned_docs/version-7.0/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-7.0/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 76701c04da..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,962 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index f63a3d807a..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,514 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - -* Note the following difference between the underlying search engines: - - * When using __Lucene__: - This metadata property is always available in the results. - - * When using __Corax__: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index f970fa79dd..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,539 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) # todo gracjan: check if its possible to order by again without then_by - # todo reeb: skip this example for now, we'll get back to it later on - # A secondary sort can be applied -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 2767086d97..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index e9e99cf398..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -| Parameter | Type | Description | -|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-count-query-results-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-customize-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..a3f3e8abc4 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,962 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..3229d3c59f --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,514 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + +* Note the following difference between the underlying search engines: + + * When using __Lucene__: + This metadata property is always available in the results. + + * When using __Corax__: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..e127cbf432 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,539 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) # todo gracjan: check if its possible to order by again without then_by + # todo reeb: skip this example for now, we'll get back to it later on + # A secondary sort can be applied +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-project-query-results-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-intersect-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..1d4b9221d7 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f0354dff46 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +| Parameter | Type | Description | +|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_sort-query-results-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/_vector-search-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/content/_vector-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/_vector-search-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/content/_vector-search-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index 157fe9e4ec..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 90c08b9c95..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index 82050a7150..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -The `QueryTimings` object will be filled with the timings when the query returns. - -| `QueryTimings` | | | -|------------------|-----------------------------|---------------------------------------------------| -| __durationInMs__ | `long` | Total duration | -| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 2594955761..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,106 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 447455323e..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index a24ff39584..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..074ff4437e --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..87f6efdabe --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..dde738eb47 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +The `QueryTimings` object will be filled with the timings when the query returns. + +| `QueryTimings` | | | +|------------------|-----------------------------|---------------------------------------------------| +| __durationInMs__ | `long` | Total duration | +| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..04c49f9a7d --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,106 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..ff61a93e87 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..ed2089f0f5 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-7.0/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-project-query-results.mdx index 005a01c964..505ff9b85d 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-7.0/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/sort-query-results.mdx index a34e918743..26b8cb85a3 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/sort-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 4d6da16a2d..0000000000 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,373 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) - -# todo reeb & gracjan: lets implement it after 5.4 release -# i have a perfect ticket for that -# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_full-text-search-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..0bf2fc548a --- /dev/null +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,373 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) + +# todo reeb & gracjan: lets implement it after 5.4 release +# i have a perfect ticket for that +# https://issues.hibernatingrhinos.com/issue/RDBC-820#focus=Comments-67-1050834.0-0 +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_proximity-search-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-php.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-php.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-python.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/session/querying/text-search/_using-regex-python.mdx rename to versioned_docs/version-7.0/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-7.0/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/querying/vector-search.mdx b/versioned_docs/version-7.0/client-api/session/querying/vector-search.mdx index 49709640a7..19b0fe51a4 100644 --- a/versioned_docs/version-7.0/client-api/session/querying/vector-search.mdx +++ b/versioned_docs/version-7.0/client-api/session/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/saving-changes.mdx b/versioned_docs/version-7.0/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/versioned_docs/version-7.0/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-7.0/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/storing-entities.mdx b/versioned_docs/version-7.0/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/versioned_docs/version-7.0/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/updating-entities.mdx b/versioned_docs/version-7.0/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/versioned_docs/version-7.0/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-7.0/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-7.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/versioned_docs/version-7.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-7.0/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-7.0/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-7.0/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-7.0/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/setting-up-default-database.mdx b/versioned_docs/version-7.0/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-7.0/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-7.0/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-7.0/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-7.0/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-7.0/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-7.0/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-7.0/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/client-api/what-is-a-document-store.mdx b/versioned_docs/version-7.0/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-7.0/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-7.0/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/data-archival/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-7.0/data-archival/_archived-documents-and-other-features-csharp.mdx deleted file mode 100644 index 3a5ba1beed..0000000000 --- a/versioned_docs/version-7.0/data-archival/_archived-documents-and-other-features-csharp.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), - RavenDB features can detect these documents and handle them in different ways. - -* Some features, like indexes and data subscriptions, provide native support for configuring whether to: - * **Exclude** archived documents from processing, reducing index size and improving query relevance. - * **Include** only archived documents, for tasks that target archived data specifically. - * **Process both** archived and non-archived documents when needed. - -* Other features can manage archived documents differently based on their purpose. For example: - * ETL tasks can skip or selectively process archived documents. - * Archived documents can be included or excluded when exporting or importing data. - -* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. - -* Learn more below about how various RavenDB features interact with archived documents. -* In this article: - * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) - * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) - * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) - * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) - * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) - * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) - * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) - * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) - * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) - * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) - - -## Archived documents and indexing - -* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. -* Archiving documents and excluding them from indexing can be an effective way to maintain performance. - By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. - This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. -* **Configuring indexing behavior - Static indexes**: - * **At the database level or server-wide**: - To control whether static indexes process archived documents from the source collection, - set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) - configuration key at either the database level or server-wide (default: `ExcludeArchived`). - * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. - This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. - * **Per index**: - You can override this global behavior per-index directly in the index definition, using the Client API from the Studio - (see the examples below). - -* **Configuring indexing behavior - Auto indexes:** - * **At the database level or server-wide**: - To control whether auto-indexes process archived documents at the database level or server-wide, - set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). - * **Per index**: - Unlike static indexes, you cannot configure this behavior per auto-index, - because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the index. - * `IncludeArchived`: both archived and non-archived documents are processed by the index. - * `ArchivedOnly`: only archived documents are processed by the index. -##### Configuring archived document processing for a static index - from the Client API - -You can configure how a static index handles archived documents when creating the index using the Client API. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`public class Orders_ByOrderDate : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public DateTime OrderDate { get; set; } - } - - public Orders_ByOrderDate() - { - Map = orders => from order in orders - select new IndexEntry - { - OrderDate = order.OrderedAt - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByOrderDate_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - return { - OrderDate: order.OrderedAt - }; - })" - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinitionBuilder() -{ - Map = orders => from order in orders - select new { order.OrderedAt } -} - .ToIndexDefinition(new DocumentConventions()); - -indexDefinition.Name = "Orders/ByOrderDate"; - -// Configure whether the index should process data from archived documents: -// ======================================================================== -indexDefinition.ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - ArchivedDataProcessingBehavior.IncludeArchived; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - - -When a static-index is configured to include **both** archived and non-archived documents in its processing, -you can also apply custom logic based on the presence of the `@archived` metadata property. - -For example: - - - - -{`public class Orders_ByArchivedStatus : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public bool? isArchived { get; set; } - public DateTime? OrderDate { get; set; } - public string ShipToCountry { get; set; } - } - - public Orders_ByArchivedStatus() - { - Map = orders => from order in orders - let metadata = MetadataFor(order) - - // Retrieve the '@archived' metadata property from the document: - let archivedProperty = - metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) - // Alternative syntax: - // let archivedProperty = - // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] - - select new IndexEntry - { - // Index whether the document is archived: - isArchived = archivedProperty == true, - - // Index the order date only if the document is archived: - OrderDate = archivedProperty == true ? order.OrderedAt : null, - - // Index the destination country only if the document is not archived: - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByArchivedStatus_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - var metadata = metadataFor(order); - var archivedProperty = metadata['@archived']; - - var isArchived = (archivedProperty === true); - - var orderDate = isArchived ? order.OrderedAt : null; - var shipToCountry = !isArchived ? order.ShipTo.Country : null; - - return { - IsArchived: isArchived, - OrderDate: orderDate, - ShipToCountry: shipToCountry - }; - })" - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "Orders/ByArchivedStatus", - - Maps = new HashSet - { - @"from order in docs.Orders - let metadata = MetadataFor(order) - let archivedProperty = (bool?)metadata[""@archived""] - - select new - { - IsArchived = archivedProperty == true, - OrderDate = archivedProperty == true ? order.OrderedAt : null, - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }" - }, - - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - -##### Configuring archived document processing for a static index - from the Studio - -You can configure how a static index handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - -![Configure index](./assets/configure-static-index.png) - -1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, - or create a new index. -2. Scroll down and open the **Archived Data** tab. -3. Click to select how this index should process archived documents: - * **Default**: The index will use the behavior set by the global configuration. - * **Exclude Archived**: Index only non-archived documents. - * **Include Archived**: Index both archived and non-archived documents. - * **Archived Only**: Index only archived documents. - -![Processing options](./assets/processing-options.png) - - - -## Archived documents and querying - -* **Full collection queries**: - * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. - * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. - * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). - -* **Dynamic queries (auto-indexes)**: - * When making a dynamic query, RavenDB creates an auto-index to serve it. - Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. - * Once created, the auto-index retains that behavior. - Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. - * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). - -* **Querying static-indexes**: - * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. - The index behavior is determined by: - * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - - * the explicit setting in the index definition, which overrides the global configuration key. - * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. - - - -## Archived documents and subscriptions - -* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. -* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. - This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. -* **Configuring the subscription task behavior**: - * **At the database level or server-wide**: - To control whether queries in data subscription tasks process archived documents, - set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide - (default: `ExcludeArchived`). - * **Per task**: - You can override this global behavior per data subscription task directly in the task definition, - using the Client API or from the Studio (see the examples below). -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the subscription query. - * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. - * `ArchivedOnly`: only archived documents are processed by the subscription query. -##### Configuring archived document processing for a data subscription task - from the Client API - -You can configure how a subscription task handles archived documents when creating the subscription using the Client API. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - Query = "from Orders", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - - -##### Configuring archived document processing for a data subscription task - from the Studio - -You can configure how a subscription task handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - -![Configure subscription](./assets/configure-subscription.png) - -1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, - or create a new subscription. -2. Click to select how the subscription query should process archived documents: - * **Default**: The subscription will use the behavior set by the global configuration. - * **Exclude Archived**: Process only non-archived documents. - * **Include Archived**: Process both archived and non-archived documents. - * **Archived Only**: Process only archived documents. - - - -## Archived documents and document extensions - -* **Attachments**: - * Attachments are Not archived (compressed), even if the document they belong to is archived. - -* **Counters**: - * Counters are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Time series**: - * Time series are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Revisions**: - * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. - * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. - - - -## Archived documents and smuggler (export/import) - -You can control whether archived documents are included when exporting or importing a database. -##### Export/Import archived documents - from the Client API - -[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. -By default, archived documents are **included** in the operation. - - - -In this example, exported data **excludes** archived documents: - - - -{`var exportOperation = store.Smuggler.ExportAsync( - new DatabaseSmugglerExportOptions() - \{ - // Export only non-archived documents: - IncludeArchived = false - \}, "DestinationFilePath"); -`} - - - - - - - -In this example, imported data **includes** archived documents: - - - -{`var importOperation = store.Smuggler.ImportAsync( - new DatabaseSmugglerImportOptions() - \{ - // Include archived documents in the import: - IncludeArchived = true - \}, "SourceFilePath"); -`} - - - - -##### Export archived documents - from the Studio - -![Export archived documents](./assets/export-archived-documents.png) - -1. Go to **Tasks > Export Database**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. -##### Import archived documents - from the Studio - -![Import archived documents](./assets/import-archived-documents.png) - -1. Go to **Tasks > Import Data**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. - - - -## Archived documents and expiration - -* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). - -* For example, a document can be scheduled to be archived after six months and expired after one year. - This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, - and eventually remove documents that are no longer needed. - -* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` - to schedule it for archiving and expiration, respectively: - - - -{`\{ - "Name": "Wilman Kala", - "Phone": "90-224 8858", - ... - "@metadata": \{ - "@archive-at": "2026-01-06T22:45:30.018Z", - "@expires": "2026-07-06T22:45:30.018Z", - "@collection": "Companies", - ... - \} -\} -`} - - - - - -## Archived documents and ETL - -* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) - for the existence of the `@archived: true` property, which indicates that the document is archived. - Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. - -* With [RavenDB ETL](../server/ongoing-tasks/etl/raven.mdx), documents that are archived in the source database and sent to the target - are not archived in the destination database. - -* In the following example, the ETL script checks whether the document is archived, and skips it if it is: - - - -{`var isArchived = this['@metadata']['@archived']; - -if (isArchived === true) \{ - return; // Do not process archived documents -\} - -// Transfer only non-archived documents to the target -loadToOrders(this); -`} - - - - - -## Archived documents and backup - -* Archived documents are included in database backups (both _logical backups_ and _snapshots_), - no special configuration is required. - -* When restoring a database from a backup, archived documents are restored as well, - and their archived status is preserved. - - - -## Archived documents and replication - -Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, -[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - -no special configuration is required. - - - -## Archived documents and patching - -* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: - [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). - [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). - -* Patching is used to **unarchive** documents. - See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). - -* When **cloning** an archived document using the `put` method within a patching script - (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, - and the `@archived: true` property will be removed from the cloned document. - - - - diff --git a/versioned_docs/version-7.0/data-archival/_enable-data-archiving-csharp.mdx b/versioned_docs/version-7.0/data-archival/_enable-data-archiving-csharp.mdx deleted file mode 100644 index 4b2741bca0..0000000000 --- a/versioned_docs/version-7.0/data-archival/_enable-data-archiving-csharp.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, data archiving is disabled. - To use the archiving feature, you must first **enable** it. - -* When configuring the feature, - you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. - -* Once enabled, the archiving task runs periodically at the configured frequency, - scanning the database for documents that have been scheduled for archival. - Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). - -* In this article: - * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) - * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) - - -## Enable archiving - from the Client API - -Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. -**Example**: - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.Send -store.Maintenance.Send(configureArchivalOp); -`} - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.SendAsync -await store.Maintenance.SendAsync(configureArchivalOp); -`} - - - -**Syntax**: - - - -{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) -`} - - - - - -{`public class DataArchivalConfiguration -\{ - public bool Disabled \{ get; set; \} - public long? ArchiveFrequencyInSec \{ get; set; \} - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | -| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | -| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | - - - -## Enable archiving - from the Studio - -![Enable archiving](./assets/enable-archiving.png) - -1. Go to **Settings > Data Archival**. -2. Toggle on to enable data archival. -3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. - Default is 60 seconds. -4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. -5. Click Save to apply your settings. - - - - diff --git a/versioned_docs/version-7.0/data-archival/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-7.0/data-archival/_schedule-document-archiving-csharp.mdx deleted file mode 100644 index cd81710280..0000000000 --- a/versioned_docs/version-7.0/data-archival/_schedule-document-archiving-csharp.mdx +++ /dev/null @@ -1,274 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents cannot be archived directly - they must be scheduled for archival. - To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). - This can be done in several ways, as described in this article. - -* **Note**: - Just scheduling a document for archival does Not archive it at the specified time. - Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). - This task periodically scans the database for documents scheduled for archival. - The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). - -* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. - The `@archive-at` metadata property will then be replaced with `@archived: true`. - -* You can schedule documents for archival even if the archiving feature is not yet enabled. - These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. -* In this article: - * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) - * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) - * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) - * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) - - -## Schedule a SINGLE document for archiving - from the Client API - -To schedule a single document for archival from the Client API, -add the `@archive-at` property directly to the document metadata as follows: - - - - -{`using (var session = store.OpenSession()) -{ - // Load the document to schedule for archiving - var company = session.Load("companies/91-A"); - - // Access the document's metadata - var metadata = session.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - // Load the document to schedule for archiving - var company = await asyncSession.LoadAsync("companies/91-A"); - - // Access the document's metadata - var metadata = asyncSession.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - -Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - - - -## Schedule a SINGLE document for archiving - from the Studio - -* To schedule a single document for archival from the Studio: - * Open the Document view. - * Add the `@archive-at` property to the document's metadata. - * Set its value to the desired archive time in UTC format. - * Save the document. - -![Schedule a document for archiving](./assets/schedule-document-for-archiving.png) - -1. This is the `@archive-at` property that was added to the document's metadata. - E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` -2. After saving the document, the Studio displays the time remaining until the document is archived. - - - -## Schedule MULTIPLE documents for archiving - from the Client API - -* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. - -* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. - In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). - -* When the patch operation is executed, - the server will add the `@archive-at` property to the metadata of all documents that match the query filter. -**Example:** - -The following example schedules all orders that were made at least a year ago for archival. -The **patch query** filters for these older orders. -Any document matching the query is then scheduled for archival by the **patch script**. - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - // The patch query: - // ================ - from Orders - where OrderedAt < '{oldDateString}' - update {{ - // The patch script - schedule for archival: - // ========================================= - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < '{oldDateString}' - update {{ - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.archiveAt(doc, utcDateTimeString) -`} - - - -| Parameter | Type | Description | -|-----------------------|-------------|--------------------------------------------------------------------------------------| -| **doc** | `object` | The document to schedule for archiving. | -| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | - -To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). - - - -## Schedule MULTIPLE documents for archiving - from the Studio - -* To schedule multiple documents for archiving from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. - -![Schedule multiple documents for archiving](./assets/schedule-multiple-documents-for-archiving.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - - diff --git a/versioned_docs/version-7.0/data-archival/_unarchiving-documents-csharp.mdx b/versioned_docs/version-7.0/data-archival/_unarchiving-documents-csharp.mdx deleted file mode 100644 index 1f12e49710..0000000000 --- a/versioned_docs/version-7.0/data-archival/_unarchiving-documents-csharp.mdx +++ /dev/null @@ -1,230 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Archived documents can be unarchived at any time. - -* The archiving feature does Not need to be enabled to unarchive documents. - Any previously archived document can be unarchived, regardless of the feature's current state. - -* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. - This will not clear the internal archived status of the document. - To properly unarchive a document, use the `archived.unarchive()` method as described below. - -* In this article: - * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) - * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) - * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) - - -## Unarchive documents - from the Client API - -* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, - which targets one or more documents based on the patch query. - -* You can apply any filtering condition within the query to target only the documents you want to unarchive. - -* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents - that match the **patch query**. -**Example:** - -The following operation will unarchive ALL archived documents in the _Orders_ collection. - - - - -{`// Define the patch query string -string patchByQuery = @" - // The patch query: - // ================ - from Orders - update - { - // The patch script: - // ================= - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.unarchive(doc) -`} - - - -| Parameter | Type | Description | -|------------|----------|----------------------------| -| **doc** | `object` | The document to unarchive. | - - - -## Unarchive documents - from the Studio - -* To unarchive documents from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.unarchive()` method. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. -It will unarchive all archived documents in the _Orders_ collection. - -![Unarchive documents](./assets/unarchive-documents.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - -## Unarchiving documents with index-based patch queries - -* When running a patch query to unarchive documents over an index, - you need to consider the index configuration regarding archived documents. - -* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - - because those documents are not included in the index. - As a result, no documents will be unarchived by the patch operation. - -* For example, the following patch query uses a dynamic query that creates an auto-index. - If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, - then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - - and the patch operation will not unarchive any documents. - - - -{`string patchByQuery = @" - // This filtering query creates an auto-index: - // =========================================== - from Orders - where ShipTo.Country == 'USA' - update - \{ - archived.unarchive(this) - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - -Two possible workarounds are: - -1. **Configure the index to include archived documents**: - This ensures archived documents are included in the index and can be matched by the patch query. - Use this option only if including archived documents in the index aligns with your indexing strategy. - - **For auto-indexes**: - Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. - **For static-indexes**: - Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, - or - configure the definition of the specific static-index to include archived documents. - See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). - -2. **Use a collection query instead of an index query**: - Run a simple collection-based query that does not rely on an index. - Apply your filtering logic inside the patch script to unarchive only the relevant documents. - - For example: - - -{`string patchByQuery = @" - // Perform a collection query: - // =========================== - from Orders as order - update - \{ - // Filter documents inside the script: - // =================================== - if (order.ShipTo.City == 'New York') - \{ - archived.unarchive(this) - \} - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - - - - - diff --git a/versioned_docs/version-7.0/data-archival/archived-documents-and-other-features.mdx b/versioned_docs/version-7.0/data-archival/archived-documents-and-other-features.mdx index 6cf644a121..6e66d0d452 100644 --- a/versioned_docs/version-7.0/data-archival/archived-documents-and-other-features.mdx +++ b/versioned_docs/version-7.0/data-archival/archived-documents-and-other-features.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ArchivedDocumentsAndOtherFeaturesCsharp from './_archived-documents-and-other-features-csharp.mdx'; +import ArchivedDocumentsAndOtherFeaturesCsharp from './content/_archived-documents-and-other-features-csharp.mdx'; diff --git a/versioned_docs/version-7.0/data-archival/content/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-7.0/data-archival/content/_archived-documents-and-other-features-csharp.mdx new file mode 100644 index 0000000000..2ffc1c20e3 --- /dev/null +++ b/versioned_docs/version-7.0/data-archival/content/_archived-documents-and-other-features-csharp.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), + RavenDB features can detect these documents and handle them in different ways. + +* Some features, like indexes and data subscriptions, provide native support for configuring whether to: + * **Exclude** archived documents from processing, reducing index size and improving query relevance. + * **Include** only archived documents, for tasks that target archived data specifically. + * **Process both** archived and non-archived documents when needed. + +* Other features can manage archived documents differently based on their purpose. For example: + * ETL tasks can skip or selectively process archived documents. + * Archived documents can be included or excluded when exporting or importing data. + +* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. + +* Learn more below about how various RavenDB features interact with archived documents. +* In this article: + * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) + * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) + * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) + * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) + * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) + * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) + * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) + * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) + * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) + * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) + + +## Archived documents and indexing + +* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. +* Archiving documents and excluding them from indexing can be an effective way to maintain performance. + By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. + This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. +* **Configuring indexing behavior - Static indexes**: + * **At the database level or server-wide**: + To control whether static indexes process archived documents from the source collection, + set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) + configuration key at either the database level or server-wide (default: `ExcludeArchived`). + * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. + This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. + * **Per index**: + You can override this global behavior per-index directly in the index definition, using the Client API from the Studio + (see the examples below). + +* **Configuring indexing behavior - Auto indexes:** + * **At the database level or server-wide**: + To control whether auto-indexes process archived documents at the database level or server-wide, + set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). + * **Per index**: + Unlike static indexes, you cannot configure this behavior per auto-index, + because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the index. + * `IncludeArchived`: both archived and non-archived documents are processed by the index. + * `ArchivedOnly`: only archived documents are processed by the index. +##### Configuring archived document processing for a static index - from the Client API + +You can configure how a static index handles archived documents when creating the index using the Client API. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`public class Orders_ByOrderDate : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public DateTime OrderDate { get; set; } + } + + public Orders_ByOrderDate() + { + Map = orders => from order in orders + select new IndexEntry + { + OrderDate = order.OrderedAt + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByOrderDate_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + return { + OrderDate: order.OrderedAt + }; + })" + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinitionBuilder() +{ + Map = orders => from order in orders + select new { order.OrderedAt } +} + .ToIndexDefinition(new DocumentConventions()); + +indexDefinition.Name = "Orders/ByOrderDate"; + +// Configure whether the index should process data from archived documents: +// ======================================================================== +indexDefinition.ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + ArchivedDataProcessingBehavior.IncludeArchived; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + + +When a static-index is configured to include **both** archived and non-archived documents in its processing, +you can also apply custom logic based on the presence of the `@archived` metadata property. + +For example: + + + + +{`public class Orders_ByArchivedStatus : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public bool? isArchived { get; set; } + public DateTime? OrderDate { get; set; } + public string ShipToCountry { get; set; } + } + + public Orders_ByArchivedStatus() + { + Map = orders => from order in orders + let metadata = MetadataFor(order) + + // Retrieve the '@archived' metadata property from the document: + let archivedProperty = + metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) + // Alternative syntax: + // let archivedProperty = + // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] + + select new IndexEntry + { + // Index whether the document is archived: + isArchived = archivedProperty == true, + + // Index the order date only if the document is archived: + OrderDate = archivedProperty == true ? order.OrderedAt : null, + + // Index the destination country only if the document is not archived: + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByArchivedStatus_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + var metadata = metadataFor(order); + var archivedProperty = metadata['@archived']; + + var isArchived = (archivedProperty === true); + + var orderDate = isArchived ? order.OrderedAt : null; + var shipToCountry = !isArchived ? order.ShipTo.Country : null; + + return { + IsArchived: isArchived, + OrderDate: orderDate, + ShipToCountry: shipToCountry + }; + })" + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "Orders/ByArchivedStatus", + + Maps = new HashSet + { + @"from order in docs.Orders + let metadata = MetadataFor(order) + let archivedProperty = (bool?)metadata[""@archived""] + + select new + { + IsArchived = archivedProperty == true, + OrderDate = archivedProperty == true ? order.OrderedAt : null, + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }" + }, + + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + +##### Configuring archived document processing for a static index - from the Studio + +You can configure how a static index handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + +![Configure index](../assets/configure-static-index.png) + +1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, + or create a new index. +2. Scroll down and open the **Archived Data** tab. +3. Click to select how this index should process archived documents: + * **Default**: The index will use the behavior set by the global configuration. + * **Exclude Archived**: Index only non-archived documents. + * **Include Archived**: Index both archived and non-archived documents. + * **Archived Only**: Index only archived documents. + +![Processing options](../assets/processing-options.png) + + + +## Archived documents and querying + +* **Full collection queries**: + * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. + * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. + * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). + +* **Dynamic queries (auto-indexes)**: + * When making a dynamic query, RavenDB creates an auto-index to serve it. + Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. + * Once created, the auto-index retains that behavior. + Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. + * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). + +* **Querying static-indexes**: + * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. + The index behavior is determined by: + * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - + * the explicit setting in the index definition, which overrides the global configuration key. + * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. + + + +## Archived documents and subscriptions + +* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. +* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. + This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. +* **Configuring the subscription task behavior**: + * **At the database level or server-wide**: + To control whether queries in data subscription tasks process archived documents, + set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide + (default: `ExcludeArchived`). + * **Per task**: + You can override this global behavior per data subscription task directly in the task definition, + using the Client API or from the Studio (see the examples below). +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the subscription query. + * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. + * `ArchivedOnly`: only archived documents are processed by the subscription query. +##### Configuring archived document processing for a data subscription task - from the Client API + +You can configure how a subscription task handles archived documents when creating the subscription using the Client API. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + Query = "from Orders", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + + +##### Configuring archived document processing for a data subscription task - from the Studio + +You can configure how a subscription task handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + +![Configure subscription](../assets/configure-subscription.png) + +1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, + or create a new subscription. +2. Click to select how the subscription query should process archived documents: + * **Default**: The subscription will use the behavior set by the global configuration. + * **Exclude Archived**: Process only non-archived documents. + * **Include Archived**: Process both archived and non-archived documents. + * **Archived Only**: Process only archived documents. + + + +## Archived documents and document extensions + +* **Attachments**: + * Attachments are Not archived (compressed), even if the document they belong to is archived. + +* **Counters**: + * Counters are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Time series**: + * Time series are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Revisions**: + * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. + * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. + + + +## Archived documents and smuggler (export/import) + +You can control whether archived documents are included when exporting or importing a database. +##### Export/Import archived documents - from the Client API + +[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. +By default, archived documents are **included** in the operation. + + + +In this example, exported data **excludes** archived documents: + + + +{`var exportOperation = store.Smuggler.ExportAsync( + new DatabaseSmugglerExportOptions() + \{ + // Export only non-archived documents: + IncludeArchived = false + \}, "DestinationFilePath"); +`} + + + + + + + +In this example, imported data **includes** archived documents: + + + +{`var importOperation = store.Smuggler.ImportAsync( + new DatabaseSmugglerImportOptions() + \{ + // Include archived documents in the import: + IncludeArchived = true + \}, "SourceFilePath"); +`} + + + + +##### Export archived documents - from the Studio + +![Export archived documents](../assets/export-archived-documents.png) + +1. Go to **Tasks > Export Database**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. +##### Import archived documents - from the Studio + +![Import archived documents](../assets/import-archived-documents.png) + +1. Go to **Tasks > Import Data**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. + + + +## Archived documents and expiration + +* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). + +* For example, a document can be scheduled to be archived after six months and expired after one year. + This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, + and eventually remove documents that are no longer needed. + +* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` + to schedule it for archiving and expiration, respectively: + + + +{`\{ + "Name": "Wilman Kala", + "Phone": "90-224 8858", + ... + "@metadata": \{ + "@archive-at": "2026-01-06T22:45:30.018Z", + "@expires": "2026-07-06T22:45:30.018Z", + "@collection": "Companies", + ... + \} +\} +`} + + + + + +## Archived documents and ETL + +* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) + for the existence of the `@archived: true` property, which indicates that the document is archived. + Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. + +* With [RavenDB ETL](../server/ongoing-tasks/etl/raven.mdx), documents that are archived in the source database and sent to the target + are not archived in the destination database. + +* In the following example, the ETL script checks whether the document is archived, and skips it if it is: + + + +{`var isArchived = this['@metadata']['@archived']; + +if (isArchived === true) \{ + return; // Do not process archived documents +\} + +// Transfer only non-archived documents to the target +loadToOrders(this); +`} + + + + + +## Archived documents and backup + +* Archived documents are included in database backups (both _logical backups_ and _snapshots_), + no special configuration is required. + +* When restoring a database from a backup, archived documents are restored as well, + and their archived status is preserved. + + + +## Archived documents and replication + +Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, +[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - +no special configuration is required. + + + +## Archived documents and patching + +* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: + [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). + [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). + +* Patching is used to **unarchive** documents. + See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). + +* When **cloning** an archived document using the `put` method within a patching script + (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, + and the `@archived: true` property will be removed from the cloned document. + + + + diff --git a/versioned_docs/version-7.0/data-archival/content/_enable-data-archiving-csharp.mdx b/versioned_docs/version-7.0/data-archival/content/_enable-data-archiving-csharp.mdx new file mode 100644 index 0000000000..cdcdfecd0f --- /dev/null +++ b/versioned_docs/version-7.0/data-archival/content/_enable-data-archiving-csharp.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, data archiving is disabled. + To use the archiving feature, you must first **enable** it. + +* When configuring the feature, + you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. + +* Once enabled, the archiving task runs periodically at the configured frequency, + scanning the database for documents that have been scheduled for archival. + Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). + +* In this article: + * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) + * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) + + +## Enable archiving - from the Client API + +Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. +**Example**: + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.Send +store.Maintenance.Send(configureArchivalOp); +`} + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.SendAsync +await store.Maintenance.SendAsync(configureArchivalOp); +`} + + + +**Syntax**: + + + +{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) +`} + + + + + +{`public class DataArchivalConfiguration +\{ + public bool Disabled \{ get; set; \} + public long? ArchiveFrequencyInSec \{ get; set; \} + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | +| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | +| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | + + + +## Enable archiving - from the Studio + +![Enable archiving](../assets/enable-archiving.png) + +1. Go to **Settings > Data Archival**. +2. Toggle on to enable data archival. +3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. + Default is 60 seconds. +4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. +5. Click Save to apply your settings. + + + + diff --git a/versioned_docs/version-7.0/data-archival/content/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-7.0/data-archival/content/_schedule-document-archiving-csharp.mdx new file mode 100644 index 0000000000..0414d08e3f --- /dev/null +++ b/versioned_docs/version-7.0/data-archival/content/_schedule-document-archiving-csharp.mdx @@ -0,0 +1,274 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents cannot be archived directly - they must be scheduled for archival. + To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). + This can be done in several ways, as described in this article. + +* **Note**: + Just scheduling a document for archival does Not archive it at the specified time. + Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). + This task periodically scans the database for documents scheduled for archival. + The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). + +* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. + The `@archive-at` metadata property will then be replaced with `@archived: true`. + +* You can schedule documents for archival even if the archiving feature is not yet enabled. + These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. +* In this article: + * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) + * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) + * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) + * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) + + +## Schedule a SINGLE document for archiving - from the Client API + +To schedule a single document for archival from the Client API, +add the `@archive-at` property directly to the document metadata as follows: + + + + +{`using (var session = store.OpenSession()) +{ + // Load the document to schedule for archiving + var company = session.Load("companies/91-A"); + + // Access the document's metadata + var metadata = session.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + // Load the document to schedule for archiving + var company = await asyncSession.LoadAsync("companies/91-A"); + + // Access the document's metadata + var metadata = asyncSession.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + +Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + + + +## Schedule a SINGLE document for archiving - from the Studio + +* To schedule a single document for archival from the Studio: + * Open the Document view. + * Add the `@archive-at` property to the document's metadata. + * Set its value to the desired archive time in UTC format. + * Save the document. + +![Schedule a document for archiving](../assets/schedule-document-for-archiving.png) + +1. This is the `@archive-at` property that was added to the document's metadata. + E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` +2. After saving the document, the Studio displays the time remaining until the document is archived. + + + +## Schedule MULTIPLE documents for archiving - from the Client API + +* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. + +* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. + In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). + +* When the patch operation is executed, + the server will add the `@archive-at` property to the metadata of all documents that match the query filter. +**Example:** + +The following example schedules all orders that were made at least a year ago for archival. +The **patch query** filters for these older orders. +Any document matching the query is then scheduled for archival by the **patch script**. + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + // The patch query: + // ================ + from Orders + where OrderedAt < '{oldDateString}' + update {{ + // The patch script - schedule for archival: + // ========================================= + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < '{oldDateString}' + update {{ + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.archiveAt(doc, utcDateTimeString) +`} + + + +| Parameter | Type | Description | +|-----------------------|-------------|--------------------------------------------------------------------------------------| +| **doc** | `object` | The document to schedule for archiving. | +| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | + +To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). + + + +## Schedule MULTIPLE documents for archiving - from the Studio + +* To schedule multiple documents for archiving from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. + +![Schedule multiple documents for archiving](../assets/schedule-multiple-documents-for-archiving.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + + diff --git a/versioned_docs/version-7.0/data-archival/content/_unarchiving-documents-csharp.mdx b/versioned_docs/version-7.0/data-archival/content/_unarchiving-documents-csharp.mdx new file mode 100644 index 0000000000..faac23a4e8 --- /dev/null +++ b/versioned_docs/version-7.0/data-archival/content/_unarchiving-documents-csharp.mdx @@ -0,0 +1,230 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Archived documents can be unarchived at any time. + +* The archiving feature does Not need to be enabled to unarchive documents. + Any previously archived document can be unarchived, regardless of the feature's current state. + +* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. + This will not clear the internal archived status of the document. + To properly unarchive a document, use the `archived.unarchive()` method as described below. + +* In this article: + * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) + * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) + * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) + + +## Unarchive documents - from the Client API + +* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, + which targets one or more documents based on the patch query. + +* You can apply any filtering condition within the query to target only the documents you want to unarchive. + +* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents + that match the **patch query**. +**Example:** + +The following operation will unarchive ALL archived documents in the _Orders_ collection. + + + + +{`// Define the patch query string +string patchByQuery = @" + // The patch query: + // ================ + from Orders + update + { + // The patch script: + // ================= + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.unarchive(doc) +`} + + + +| Parameter | Type | Description | +|------------|----------|----------------------------| +| **doc** | `object` | The document to unarchive. | + + + +## Unarchive documents - from the Studio + +* To unarchive documents from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.unarchive()` method. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. +It will unarchive all archived documents in the _Orders_ collection. + +![Unarchive documents](../assets/unarchive-documents.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + +## Unarchiving documents with index-based patch queries + +* When running a patch query to unarchive documents over an index, + you need to consider the index configuration regarding archived documents. + +* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - + because those documents are not included in the index. + As a result, no documents will be unarchived by the patch operation. + +* For example, the following patch query uses a dynamic query that creates an auto-index. + If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, + then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - + and the patch operation will not unarchive any documents. + + + +{`string patchByQuery = @" + // This filtering query creates an auto-index: + // =========================================== + from Orders + where ShipTo.Country == 'USA' + update + \{ + archived.unarchive(this) + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + +Two possible workarounds are: + +1. **Configure the index to include archived documents**: + This ensures archived documents are included in the index and can be matched by the patch query. + Use this option only if including archived documents in the index aligns with your indexing strategy. + + **For auto-indexes**: + Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. + **For static-indexes**: + Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, + or - configure the definition of the specific static-index to include archived documents. + See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). + +2. **Use a collection query instead of an index query**: + Run a simple collection-based query that does not rely on an index. + Apply your filtering logic inside the patch script to unarchive only the relevant documents. + + For example: + + +{`string patchByQuery = @" + // Perform a collection query: + // =========================== + from Orders as order + update + \{ + // Filter documents inside the script: + // =================================== + if (order.ShipTo.City == 'New York') + \{ + archived.unarchive(this) + \} + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + + + + + diff --git a/versioned_docs/version-7.0/data-archival/enable-data-archiving.mdx b/versioned_docs/version-7.0/data-archival/enable-data-archiving.mdx index 5792991f3d..8b1d5eb068 100644 --- a/versioned_docs/version-7.0/data-archival/enable-data-archiving.mdx +++ b/versioned_docs/version-7.0/data-archival/enable-data-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableDataArchivingCsharp from './_enable-data-archiving-csharp.mdx'; +import EnableDataArchivingCsharp from './content/_enable-data-archiving-csharp.mdx'; diff --git a/versioned_docs/version-7.0/data-archival/schedule-document-archiving.mdx b/versioned_docs/version-7.0/data-archival/schedule-document-archiving.mdx index c22e6a21ed..09b032fc17 100644 --- a/versioned_docs/version-7.0/data-archival/schedule-document-archiving.mdx +++ b/versioned_docs/version-7.0/data-archival/schedule-document-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ScheduleDocumentArchivingCsharp from './_schedule-document-archiving-csharp.mdx'; +import ScheduleDocumentArchivingCsharp from './content/_schedule-document-archiving-csharp.mdx'; diff --git a/versioned_docs/version-7.0/data-archival/unarchiving-documents.mdx b/versioned_docs/version-7.0/data-archival/unarchiving-documents.mdx index 808769d015..89afcf916d 100644 --- a/versioned_docs/version-7.0/data-archival/unarchiving-documents.mdx +++ b/versioned_docs/version-7.0/data-archival/unarchiving-documents.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UnarchivingDocumentsCsharp from './_unarchiving-documents-csharp.mdx'; +import UnarchivingDocumentsCsharp from './content/_unarchiving-documents-csharp.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/bulk-insert.mdx b/versioned_docs/version-7.0/document-extensions/attachments/bulk-insert.mdx index c763b6a3ca..296538d2fa 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/bulk-insert.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/bulk-insert.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BulkInsertCsharp from './_bulk-insert-csharp.mdx'; -import BulkInsertPython from './_bulk-insert-python.mdx'; -import BulkInsertNodejs from './_bulk-insert-nodejs.mdx'; +import BulkInsertCsharp from './content/_bulk-insert-csharp.mdx'; +import BulkInsertPython from './content/_bulk-insert-python.mdx'; +import BulkInsertNodejs from './content/_bulk-insert-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_bulk-insert-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_bulk-insert-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-php.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-php.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_copying-moving-renaming-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_copying-moving-renaming-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_deleting-php.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_deleting-php.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_deleting-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_deleting-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_deleting-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_indexing-php.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_indexing-php.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_indexing-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_indexing-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_loading-php.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_loading-php.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_loading-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_loading-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_loading-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_loading-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_storing-php.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_storing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_storing-php.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_storing-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_storing-python.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_storing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_storing-python.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_storing-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-7.0/document-extensions/attachments/copying-moving-renaming.mdx index 5d9756c7ff..dd66ad7797 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; -import CopyingMovingRenamingPython from './_copying-moving-renaming-python.mdx'; -import CopyingMovingRenamingPhp from './_copying-moving-renaming-php.mdx'; -import CopyingMovingRenamingNodejs from './_copying-moving-renaming-nodejs.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingPython from './content/_copying-moving-renaming-python.mdx'; +import CopyingMovingRenamingPhp from './content/_copying-moving-renaming-php.mdx'; +import CopyingMovingRenamingNodejs from './content/_copying-moving-renaming-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/deleting.mdx b/versioned_docs/version-7.0/document-extensions/attachments/deleting.mdx index 412aa66a67..604c4058e7 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/deleting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingPython from './_deleting-python.mdx'; -import DeletingPhp from './_deleting-php.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingPython from './content/_deleting-python.mdx'; +import DeletingPhp from './content/_deleting-php.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/indexing.mdx b/versioned_docs/version-7.0/document-extensions/attachments/indexing.mdx index d49e97610c..8fca84b22e 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/loading.mdx b/versioned_docs/version-7.0/document-extensions/attachments/loading.mdx index b845db6865..6c82d701c2 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/storing.mdx b/versioned_docs/version-7.0/document-extensions/attachments/storing.mdx index 5e877c3b82..cb3e3b93d1 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/storing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringPython from './_storing-python.mdx'; -import StoringPhp from './_storing-php.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringPython from './content/_storing-python.mdx'; +import StoringPhp from './content/_storing-php.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-7.0/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-7.0/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-7.0/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_counters-and-other-features-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_create-or-modify-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_delete-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_delete-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_delete-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_delete-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_delete-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_delete-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_delete-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_delete-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_including-counters-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_including-counters-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_including-counters-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_including-counters-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_including-counters-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_including-counters-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_including-counters-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_including-counters-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_including-counters-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_including-counters-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_including-counters-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_indexing-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_indexing-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_indexing-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_indexing-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_overview-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_overview-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_overview-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_overview-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_overview-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_overview-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_overview-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-php.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-php.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-python.mdx b/versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/counters/_retrieve-counter-values-python.mdx rename to versioned_docs/version-7.0/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-7.0/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-7.0/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/delete.mdx b/versioned_docs/version-7.0/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/including-counters.mdx b/versioned_docs/version-7.0/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/including-counters.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/indexing.mdx b/versioned_docs/version-7.0/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/overview.mdx b/versioned_docs/version-7.0/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-7.0/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/versioned_docs/version-7.0/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-7.0/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 0f0c9f41b9..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,327 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index c51d9e1b8f..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,324 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_overview-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 8cb585b701..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,287 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 1906658a54..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index 3c8783a8ad..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index d42399f08e..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/_overview-python.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/delete-revisions.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/delete-revisions.mdx index 52d57a6d9e..6ac42ce584 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/delete-revisions.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/delete-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteRevisionsCsharp from './_delete-revisions-csharp.mdx'; +import DeleteRevisionsCsharp from './content/_delete-revisions-csharp.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_counting-python.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_including-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-php.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/client-api/session/_loading-python.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..3adf41e824 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,327 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..60af21c283 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,324 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..ad06ca3084 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,287 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..335c0a220b --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6bf087d689 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..ab3a281b0b --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.0/document-extensions/revisions/overview.mdx b/versioned_docs/version-7.0/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/overview.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx deleted file mode 100644 index 1ca0053750..0000000000 --- a/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx +++ /dev/null @@ -1,221 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ContentFrame from '@site/src/components/ContentFrame'; -import Panel from '@site/src/components/Panel'; - - - -* This article describes how to revert specific documents to **specific revisions**. - To revert documents from all collections (or from selected collections) to a **specific point in time**, - see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). - -* In this article: - * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) - * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) - * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) - * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) - * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) - - - - - -* When reverting to a specific revision, - the document content will be overwritten by the content of the specified revision. - -* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: - * **When revisions are ENABLED**: - Reverting the document creates a new revision containing the content of the target revision. - * **When revisions are DISABLED**: - The document is reverted to the target revision without creating a new revision. - -* In addition to the document itself, reverting will impact _Document Extensions_ as follows: - * **Attachments**: - If the target revision owns attachments, they are restored to their state when the revision was created. - * **Counters**: - If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. - * **Time series**: - Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). - - - - - -* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. - -* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). - To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). - -* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. - The document content will be overwritten by the content of the specified revision. - -* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. - -* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, - the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. - ---- - -### How to obtain a revision's change-vector: - -The change-vector of a revision can be obtained via: - - * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) - * Or from the document view in the Studio - -![Get revision CV](./assets/get-cv-for-revision.png) - -1. Go to the Revisions tab in the document view. -2. Click a revision to view -3. The document view will display the content of the revision. - This top label indicates that you are viewing a revision and not the current document. -4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. - - - - - -Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. -In this example, we revert document _orders/1-A_ to its very first revision. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "Orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); -} -``` - - - - - - - -You can use the operation to revert multiple documents. -Note: The documents do not need to belong to the same collection. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - var revisionsMetadata2 = session.Advanced.Revisions - .GetMetadataFor(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "orders/1-A"); - var revisionsMetadata2 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - - - - - - -### `RevertRevisionsByIdOperation` - - -```csharp -Available overloads: -==================== -public RevertRevisionsByIdOperation(string id, string cv); -public RevertRevisionsByIdOperation(Dictionary idToChangeVector); -``` - - -| Parameter | Type | Description | -|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| **id** | `string` | The ID of the document to revert. | -| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | -| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | - - \ No newline at end of file diff --git a/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx new file mode 100644 index 0000000000..df41e24beb --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx @@ -0,0 +1,221 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* This article describes how to revert specific documents to **specific revisions**. + To revert documents from all collections (or from selected collections) to a **specific point in time**, + see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). + +* In this article: + * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) + * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) + * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) + * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) + * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) + + + + + +* When reverting to a specific revision, + the document content will be overwritten by the content of the specified revision. + +* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: + * **When revisions are ENABLED**: + Reverting the document creates a new revision containing the content of the target revision. + * **When revisions are DISABLED**: + The document is reverted to the target revision without creating a new revision. + +* In addition to the document itself, reverting will impact _Document Extensions_ as follows: + * **Attachments**: + If the target revision owns attachments, they are restored to their state when the revision was created. + * **Counters**: + If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. + * **Time series**: + Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). + + + + + +* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. + +* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). + To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). + +* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. + The document content will be overwritten by the content of the specified revision. + +* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. + +* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, + the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. + +--- + +### How to obtain a revision's change-vector: + +The change-vector of a revision can be obtained via: + + * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) + * Or from the document view in the Studio + +![Get revision CV](../assets/get-cv-for-revision.png) + +1. Go to the Revisions tab in the document view. +2. Click a revision to view +3. The document view will display the content of the revision. + This top label indicates that you are viewing a revision and not the current document. +4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. + + + + + +Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. +In this example, we revert document _orders/1-A_ to its very first revision. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "Orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); +} +``` + + + + + + + +You can use the operation to revert multiple documents. +Note: The documents do not need to belong to the same collection. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + var revisionsMetadata2 = session.Advanced.Revisions + .GetMetadataFor(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "orders/1-A"); + var revisionsMetadata2 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + + + + + + +### `RevertRevisionsByIdOperation` + + +```csharp +Available overloads: +==================== +public RevertRevisionsByIdOperation(string id, string cv); +public RevertRevisionsByIdOperation(Dictionary idToChangeVector); +``` + + +| Parameter | Type | Description | +|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| **id** | `string` | The ID of the document to revert. | +| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | +| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | + + \ No newline at end of file diff --git a/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx b/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx index 041ad50de9..3586680073 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevertDocumentsToSpecificRevisionsCsharp from './_revert-documents-to-specific-revisions-csharp.mdx'; +import RevertDocumentsToSpecificRevisionsCsharp from './content/_revert-documents-to-specific-revisions-csharp.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-7.0/document-extensions/revisions/revisions-and-other-features.mdx index dd80b671dc..38db72b2c8 100644 --- a/versioned_docs/version-7.0/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-7.0/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 5972ad8ca5..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,300 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 2c0c4c1a5b..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,257 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index af9e9480f6..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index aa992fed57..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,309 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/javascript-support.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/named-time-series-values.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/get.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/get.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/patch.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/overview.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/overview.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/append.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/append.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_append-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/delete.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/delete.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-names.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/overview.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/patch.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/patch.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/querying.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/querying.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_design-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_design-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_design-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_design-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_indexing-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_indexing-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_indexing-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_indexing-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_indexing-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_indexing-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/_indexing-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/_indexing-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..c0d3e3b2c5 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,300 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..57c5f44e40 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,257 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..7da93ce29a --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..5d3e24fd7f --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,309 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/design.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/design.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/indexing.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/indexing.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 18ae9a014f..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,313 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index 3c635a3470..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,333 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index cb160b6ec6..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,282 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index 2025bccf4a..0000000000 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/choosing-query-range.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_filtering-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..1b0383ae1e --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,313 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..d4b5203c2b --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,333 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..76bcc0b26c --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,282 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..11bb66c408 --- /dev/null +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-php.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-python.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to versioned_docs/version-7.0/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/filtering.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/filtering.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/overview-and-syntax.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/querying/using-indexes.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/querying/using-indexes.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/rollup-and-retention.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/rollup-and-retention.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/document-extensions/timeseries/time-series-and-other-features.mdx b/versioned_docs/version-7.0/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/versioned_docs/version-7.0/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/versioned_docs/version-7.0/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-7.0/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-7.0/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-7.0/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_delete-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_delete-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_delete-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_index-query-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_index-query-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_put-compare-exchange-command-data-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_put-compare-exchange-command-data-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_put-compare-exchange-command-data-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_query-result-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_query-result-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/_stream-result-csharp.mdx b/versioned_docs/version-7.0/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-7.0/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-7.0/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-7.0/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-7.0/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/counters-batch-command-data.mdx b/versioned_docs/version-7.0/glossary/counters-batch-command-data.mdx index cdd5c4aad1..d8b4ed44a7 100644 --- a/versioned_docs/version-7.0/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/delete-command-data.mdx b/versioned_docs/version-7.0/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-7.0/glossary/delete-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/delete-compare-exchange-command-data.mdx b/versioned_docs/version-7.0/glossary/delete-compare-exchange-command-data.mdx index d98b33b1db..46e6b8e9a8 100644 --- a/versioned_docs/version-7.0/glossary/delete-compare-exchange-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/delete-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCompareExchangeCommandDataCsharp from './_delete-compare-exchange-command-data-csharp.mdx'; +import DeleteCompareExchangeCommandDataCsharp from './content/_delete-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/index-query.mdx b/versioned_docs/version-7.0/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-7.0/glossary/index-query.mdx +++ b/versioned_docs/version-7.0/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/move-attachment-command-data.mdx b/versioned_docs/version-7.0/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-7.0/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/patch-command-data.mdx b/versioned_docs/version-7.0/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-7.0/glossary/patch-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/put-command-data.mdx b/versioned_docs/version-7.0/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-7.0/glossary/put-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/put-compare-exchange-command-data.mdx b/versioned_docs/version-7.0/glossary/put-compare-exchange-command-data.mdx index d1d43f12ff..a59060d527 100644 --- a/versioned_docs/version-7.0/glossary/put-compare-exchange-command-data.mdx +++ b/versioned_docs/version-7.0/glossary/put-compare-exchange-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCompareExchangeCommandDataCsharp from './_put-compare-exchange-command-data-csharp.mdx'; +import PutCompareExchangeCommandDataCsharp from './content/_put-compare-exchange-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/query-result.mdx b/versioned_docs/version-7.0/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-7.0/glossary/query-result.mdx +++ b/versioned_docs/version-7.0/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/stream-query-statistics.mdx b/versioned_docs/version-7.0/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-7.0/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-7.0/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-7.0/glossary/stream-result.mdx b/versioned_docs/version-7.0/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-7.0/glossary/stream-result.mdx +++ b/versioned_docs/version-7.0/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-7.0/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-7.0/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-nested-data-php.mdx b/versioned_docs/version-7.0/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-nested-data-python.mdx b/versioned_docs/version-7.0/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-7.0/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-7.0/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-related-documents-php.mdx b/versioned_docs/version-7.0/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.0/indexes/_indexing-related-documents-python.mdx b/versioned_docs/version-7.0/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/versioned_docs/version-7.0/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.0/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-7.0/indexes/_storing-data-in-index-csharp.mdx deleted file mode 100644 index d588e9caf4..0000000000 --- a/versioned_docs/version-7.0/indexes/_storing-data-in-index-csharp.mdx +++ /dev/null @@ -1,409 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB allows you to store data in a static index. - -* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), - without requiring the server to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - -* In this article: - * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) - * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) - * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) - * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) - - -## What content is stored in the index - -* A static index is defined by its map function which determines the content of each **index-entry**. - Typically, a single index-entry is created for each document from the indexed source collection - - unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. - -* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. - The content of an index-field can be a direct value from the source document field, - or a computed value based on the source document's content. - -* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). - The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. - -* **RavenDB allows you to store the original index-field value in the index**. - **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. - * The tokens (terms) generated by the analyzer are searchable but not stored. - * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) - (by default they are not stored). - -* This behavior is supported by both Lucene and Corax search engines. - - - -## When and why to store data in an index - -* **Store a field in the index if**: - - * **You want to project that field without loading the full document.** - Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. - If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. - * **The index-field is a computed value that you want to return in the query results.** - Normally, querying an index returns matching documents. - But if you're projecting a computed index-field that is Not stored, - you'll need to re-calculate the computed value manually from the documents returned by the query. - Storing the computed field avoids this extra step. - -* **You do not need to store a field in the index in order to**: - - * Filter by the field in a query. - * Perform full-text search on the field. - -* **Disadvantage of storing data in the index**: - - * Increased disk space usage - stored fields take up additional space and increase index size. - - - -## Storing data in index - from the Client API - -To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). -The default is `FieldStorage.No`. -**Index example:** - - - - -{`public class QuantityOrdered_ByCompany : - AbstractIndexCreationTask -{ - // The index-entry: - public class IndexEntry - { - // The index-fields: - public string Company { get; set; } - public string CompanyName { get; set; } - public int TotalItemsOrdered { get; set; } - } - - public QuantityOrdered_ByCompany() - { - Map = orders => from order in orders - select new IndexEntry - { - // 'Company' is a SIMPLE index-field, - // its value is taken directly from the Order document: - Company = order.Company, - - // 'CompanyName' is also considered a simple index-field, - // its value is taken from the related Company document: - CompanyName = LoadDocument(order.Company).Name, - - // 'TotalItemsOrdered' is a COMPUTED index-field: - // (the total quantity of items ordered in an Order document) - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }; - - // Store the calculated 'TotalItemsOrdered' index-field in the index: - // ================================================================== - Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); - - // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: - // ======================================================================================= - Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); - - // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): - // ============================================================================= - Stores.Add(x => x.CompanyName, FieldStorage.Yes); - } -} -`} - - - - -{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask -{ - public QuantityOrdered_ByCompany_JS() - { - Maps = new HashSet() - { - @"map('orders', function(order) { - let company = load(order.Company, 'Companies') - return { - Company: order.Company, - CompanyName: company.Name, - TotalItemsOrdered: order.Lines.reduce(function(total, line) { - return total + line.Quantity; - }, 0) - }; - })" - }; - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - }; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "QuantityOrdered/ByCompany", - - Maps = - { - @"from order in docs.Orders - select new - { - Company = order.Company, - CompanyName = LoadDocument(order.Company, ""Companies"").Name, - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }" - }, - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - } -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -**Querying the index and projecting results:** - - - -* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. - -* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. - The server does Not need to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class NumberOfItemsOrdered -{ - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select TotalItemsOrdered -`} - - - - - - - -* In this query, the projected results are defined by the custom class `ProjectedDetails`. - -* In this case, some of the fields in this class are Not stored in the index, so by default, - the server does need to load the original document from storage to complete the projection. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class ProjectedDetails -{ - // This field was Not stored in the index definition - public string Company { get; set; } - // This field was Not stored in the index definition - public DateTime OrderedAt { get; set; } - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select Company, OrderedAt, TotalItemsOrdered -`} - - - - - - - -## Storing data in index - from the Studio - -To configure index-fields from the Studio, open the _Edit Index_ view: - -![The index](./assets/store-field-in-index-1.png) - -1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). -2. These are the index-fields defined in the index map function. -Scroll down to configure each index-field: - -![Configure index fields](./assets/store-field-in-index-2.png) - -1. Open the _Fields_ tab. -2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. -3. Select _Yes_ from the dropdown to store the field in the index. -4. Here we configure index-field `CompanyName`. -5. This index-field is stored in the index and also configured for full-text search. -When querying the index from the Studio, -you can choose to display the stored index fields in the Results view: - -![Display the stored fields](./assets/store-field-in-index-3.png) - -1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). -2. Open the _Settings_ options. -3. Toggle ON _Show stored index fields only_. -4. When executing the query, - the results will display the stored index-fields for each object returned by the query. - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-7.0/indexes/_using-analyzers-csharp.mdx deleted file mode 100644 index 0c33a1d29f..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-analyzers-csharp.mdx +++ /dev/null @@ -1,691 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - - 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - - 2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - use the `Analyzers.Add()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`// The index definition -public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string[] Tags { get; set; } - public string Content { get; set; } - } - - public BlogPosts_ByTagsAndContent() - { - Map = posts => from post in posts - select new IndexEntry() - { - Tags = post.Tags, - Content = post.Content - }; - - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - Analyzers.Add(x => x.Content, - typeof(SnowballAnalyzer).AssemblyQualifiedName); - } -} -`} - - - - -{`// The index definition -var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") -{ - Map = posts => from post in posts - select new {post.Tags, post.Content}, - - Analyzers = - { - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - {x => x.Tags, "SimpleAnalyzer"}, - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} - } -}.ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `FieldIndexing.Exact` - * `FieldIndexing.Search` - * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`public class BlogPosts_ByContent : AbstractIndexCreationTask -\{ - public BlogPosts_ByContent() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Search' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.Search); - - // => Index-field 'Content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `FieldIndexing.Exact`, - RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask -\{ - public Employees_ByFirstAndLastName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName, - FirstName = employee.FirstName - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Exact' on index-field 'FirstName' - Indexes.Add(x => x.FirstName, FieldIndexing.Exact); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstName : AbstractIndexCreationTask -\{ - public Employees_ByFirstName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName - \}; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`public class BlogPosts_ByTitle : AbstractIndexCreationTask -\{ - public BlogPosts_ByTitle() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.No' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.No); - - // Set 'FieldStorage.Yes' to store the original content of field 'Content' - // in the index - Stores.Add(x => x.Content, FieldStorage.Yes); - - // => No analyzer will process field 'Content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public class AnalyzerDefinition -\{ - // Name of the analyzer - public string Name \{ get; set; \} - - // C# source-code of the analyzer - public string Code \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`// Define the put analyzer operation: -var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition -\{ - // The name must be same as the analyzer's class name - Name = "MyAnalyzer", - - Code = @" - using System.IO; - using Lucene.Net.Analysis; - using Lucene.Net.Analysis.Standard; - - namespace MyAnalyzer - \{ - public class MyAnalyzer : Lucene.Net.Analysis.Analyzer - \{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - throw new CodeOmitted(); - \} - \} - \}" -\}); - -// Deploy the analyzer: -store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-7.0/indexes/_using-analyzers-nodejs.mdx deleted file mode 100644 index b120b39ea1..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-analyzers-nodejs.mdx +++ /dev/null @@ -1,655 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - -1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - -2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - set the `analyze()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content - })\`; - - // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer - this.analyze("tags", "SimpleAnalyzer"); - - // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer - this.analyze("content", "Raven.Sample.SnowballAnalyzer"); - } -} -`} - - - - -{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); -builder.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content -})\`; -builder.analyzersStrings["tags"] = "SimpleAnalyzer"; -builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; - -await store.maintenance - .send(new PutIndexesOperation( - builder.toIndexDefinition(store.conventions))); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `Exact` - * `Search` - * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Search' on index-field 'content' - this.index("content", "Search"); - - // => Index-field 'content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FirstName = employee.FirstName " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Exact' on index-field 'FirstName' - this.index("FirstName", "Exact"); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName" + - "\})"; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'No' on index-field 'content' - this.index("content", "No"); - - // Set 'Yes' to store the original content of field 'content' in the index - this.store("content", "Yes"); - - // => No analyzer will process field 'content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`const analyzerDefinition = \{ - name: "analyzerName", - code: "code" -\}; -`} - - - -| Parameter | Type | Description | -|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`const analyzerDefinition = \{ - name: "MyAnalyzer", - code: "using System.IO;\\n" + - "using Lucene.Net.Analysis;\\n" + - "using Lucene.Net.Analysis.Standard;\\n" + - "\\n" + - "namespace MyAnalyzer\\n" + - "\{\\n" + - " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + - " \{\\n" + - " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + - " \{\\n" + - " throw new CodeOmitted();\\n" + - " \}\\n" + - " \}\\n" + - "\}\\n" -\}; - -await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-7.0/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 30631bba09..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,550 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-7.0/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 2866006674..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,480 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-7.0/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 9bda34e83c..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-php.mdx b/versioned_docs/version-7.0/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index d57827b1a7..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,560 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-python.mdx b/versioned_docs/version-7.0/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index ffbfebfff6..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,512 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.0/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-7.0/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/versioned_docs/version-7.0/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/versioned_docs/version-7.0/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index f784c64ebd..0000000000 --- a/versioned_docs/version-7.0/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.0/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-7.0/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index bc0dfd5fef..0000000000 --- a/versioned_docs/version-7.0/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.0/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/versioned_docs/version-7.0/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.0/indexes/_what-are-indexes-php.mdx b/versioned_docs/version-7.0/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/versioned_docs/version-7.0/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.0/indexes/_what-are-indexes-python.mdx b/versioned_docs/version-7.0/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/versioned_docs/version-7.0/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.0/indexes/boosting.mdx b/versioned_docs/version-7.0/indexes/boosting.mdx index 1a4f9e8126..e7a5bb4fd1 100644 --- a/versioned_docs/version-7.0/indexes/boosting.mdx +++ b/versioned_docs/version-7.0/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/_boosting-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_boosting-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_boosting-java.mdx b/versioned_docs/version-7.0/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_boosting-java.mdx rename to versioned_docs/version-7.0/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_boosting-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_boosting-php.mdx b/versioned_docs/version-7.0/indexes/content/_boosting-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_boosting-php.mdx rename to versioned_docs/version-7.0/indexes/content/_boosting-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-7.0/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-7.0/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_extending-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-basics-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-compare-exchange-values-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-compare-exchange-values-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-metadata-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-metadata-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-metadata-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-metadata-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-metadata-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-metadata-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-metadata-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-metadata-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-metadata-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-metadata-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-metadata-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-metadata-php.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-metadata-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-metadata-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-metadata-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-metadata-python.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-metadata-python.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.0/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.0/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-spatial-data-php.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-spatial-data-php.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_indexing-spatial-data-python.mdx b/versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_indexing-spatial-data-python.mdx rename to versioned_docs/version-7.0/indexes/content/_indexing-spatial-data-python.mdx diff --git a/versioned_docs/version-7.0/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-indexes-php.mdx b/versioned_docs/version-7.0/indexes/content/_map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-indexes-php.mdx rename to versioned_docs/version-7.0/indexes/content/_map-indexes-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-indexes-python.mdx b/versioned_docs/version-7.0/indexes/content/_map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-indexes-python.mdx rename to versioned_docs/version-7.0/indexes/content/_map-indexes-python.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-reduce-indexes-php.mdx b/versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-reduce-indexes-php.mdx rename to versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_map-reduce-indexes-python.mdx b/versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_map-reduce-indexes-python.mdx rename to versioned_docs/version-7.0/indexes/content/_map-reduce-indexes-python.mdx diff --git a/versioned_docs/version-7.0/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_multi-map-indexes-php.mdx b/versioned_docs/version-7.0/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_multi-map-indexes-php.mdx rename to versioned_docs/version-7.0/indexes/content/_multi-map-indexes-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_multi-map-indexes-python.mdx b/versioned_docs/version-7.0/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_multi-map-indexes-python.mdx rename to versioned_docs/version-7.0/indexes/content/_multi-map-indexes-python.mdx diff --git a/versioned_docs/version-7.0/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-7.0/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-7.0/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-7.0/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/_stale-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-7.0/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-csharp.mdx new file mode 100644 index 0000000000..08e46be32f --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-csharp.mdx @@ -0,0 +1,409 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB allows you to store data in a static index. + +* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), + without requiring the server to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + +* In this article: + * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) + * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) + * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) + * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) + + +## What content is stored in the index + +* A static index is defined by its map function which determines the content of each **index-entry**. + Typically, a single index-entry is created for each document from the indexed source collection - + unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. + +* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. + The content of an index-field can be a direct value from the source document field, + or a computed value based on the source document's content. + +* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). + The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. + +* **RavenDB allows you to store the original index-field value in the index**. + **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. + * The tokens (terms) generated by the analyzer are searchable but not stored. + * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) + (by default they are not stored). + +* This behavior is supported by both Lucene and Corax search engines. + + + +## When and why to store data in an index + +* **Store a field in the index if**: + + * **You want to project that field without loading the full document.** + Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. + If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. + * **The index-field is a computed value that you want to return in the query results.** + Normally, querying an index returns matching documents. + But if you're projecting a computed index-field that is Not stored, + you'll need to re-calculate the computed value manually from the documents returned by the query. + Storing the computed field avoids this extra step. + +* **You do not need to store a field in the index in order to**: + + * Filter by the field in a query. + * Perform full-text search on the field. + +* **Disadvantage of storing data in the index**: + + * Increased disk space usage - stored fields take up additional space and increase index size. + + + +## Storing data in index - from the Client API + +To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). +The default is `FieldStorage.No`. +**Index example:** + + + + +{`public class QuantityOrdered_ByCompany : + AbstractIndexCreationTask +{ + // The index-entry: + public class IndexEntry + { + // The index-fields: + public string Company { get; set; } + public string CompanyName { get; set; } + public int TotalItemsOrdered { get; set; } + } + + public QuantityOrdered_ByCompany() + { + Map = orders => from order in orders + select new IndexEntry + { + // 'Company' is a SIMPLE index-field, + // its value is taken directly from the Order document: + Company = order.Company, + + // 'CompanyName' is also considered a simple index-field, + // its value is taken from the related Company document: + CompanyName = LoadDocument(order.Company).Name, + + // 'TotalItemsOrdered' is a COMPUTED index-field: + // (the total quantity of items ordered in an Order document) + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }; + + // Store the calculated 'TotalItemsOrdered' index-field in the index: + // ================================================================== + Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); + + // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: + // ======================================================================================= + Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); + + // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): + // ============================================================================= + Stores.Add(x => x.CompanyName, FieldStorage.Yes); + } +} +`} + + + + +{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask +{ + public QuantityOrdered_ByCompany_JS() + { + Maps = new HashSet() + { + @"map('orders', function(order) { + let company = load(order.Company, 'Companies') + return { + Company: order.Company, + CompanyName: company.Name, + TotalItemsOrdered: order.Lines.reduce(function(total, line) { + return total + line.Quantity; + }, 0) + }; + })" + }; + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + }; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "QuantityOrdered/ByCompany", + + Maps = + { + @"from order in docs.Orders + select new + { + Company = order.Company, + CompanyName = LoadDocument(order.Company, ""Companies"").Name, + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }" + }, + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + } +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +**Querying the index and projecting results:** + + + +* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. + +* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. + The server does Not need to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class NumberOfItemsOrdered +{ + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select TotalItemsOrdered +`} + + + + + + + +* In this query, the projected results are defined by the custom class `ProjectedDetails`. + +* In this case, some of the fields in this class are Not stored in the index, so by default, + the server does need to load the original document from storage to complete the projection. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class ProjectedDetails +{ + // This field was Not stored in the index definition + public string Company { get; set; } + // This field was Not stored in the index definition + public DateTime OrderedAt { get; set; } + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select Company, OrderedAt, TotalItemsOrdered +`} + + + + + + + +## Storing data in index - from the Studio + +To configure index-fields from the Studio, open the _Edit Index_ view: + +![The index](../assets/store-field-in-index-1.png) + +1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). +2. These are the index-fields defined in the index map function. +Scroll down to configure each index-field: + +![Configure index fields](../assets/store-field-in-index-2.png) + +1. Open the _Fields_ tab. +2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. +3. Select _Yes_ from the dropdown to store the field in the index. +4. Here we configure index-field `CompanyName`. +5. This index-field is stored in the index and also configured for full-text search. +When querying the index from the Studio, +you can choose to display the stored index fields in the Results view: + +![Display the stored fields](../assets/store-field-in-index-3.png) + +1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). +2. Open the _Settings_ options. +3. Toggle ON _Show stored index fields only_. +4. When executing the query, + the results will display the stored index-fields for each object returned by the query. + + + + diff --git a/versioned_docs/version-7.0/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-7.0/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/_storing-data-in-index-php.mdx b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_storing-data-in-index-php.mdx rename to versioned_docs/version-7.0/indexes/content/_storing-data-in-index-php.mdx diff --git a/versioned_docs/version-7.0/indexes/_storing-data-in-index-python.mdx b/versioned_docs/version-7.0/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_storing-data-in-index-python.mdx rename to versioned_docs/version-7.0/indexes/content/_storing-data-in-index-python.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_using-analyzers-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_using-analyzers-csharp.mdx new file mode 100644 index 0000000000..ee633b3da5 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-analyzers-csharp.mdx @@ -0,0 +1,691 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + + 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + + 2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + use the `Analyzers.Add()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`// The index definition +public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string[] Tags { get; set; } + public string Content { get; set; } + } + + public BlogPosts_ByTagsAndContent() + { + Map = posts => from post in posts + select new IndexEntry() + { + Tags = post.Tags, + Content = post.Content + }; + + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + Analyzers.Add(x => x.Content, + typeof(SnowballAnalyzer).AssemblyQualifiedName); + } +} +`} + + + + +{`// The index definition +var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") +{ + Map = posts => from post in posts + select new {post.Tags, post.Content}, + + Analyzers = + { + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + {x => x.Tags, "SimpleAnalyzer"}, + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} + } +}.ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `FieldIndexing.Exact` + * `FieldIndexing.Search` + * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`public class BlogPosts_ByContent : AbstractIndexCreationTask +\{ + public BlogPosts_ByContent() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Search' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.Search); + + // => Index-field 'Content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `FieldIndexing.Exact`, + RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask +\{ + public Employees_ByFirstAndLastName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName, + FirstName = employee.FirstName + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Exact' on index-field 'FirstName' + Indexes.Add(x => x.FirstName, FieldIndexing.Exact); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstName : AbstractIndexCreationTask +\{ + public Employees_ByFirstName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName + \}; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`public class BlogPosts_ByTitle : AbstractIndexCreationTask +\{ + public BlogPosts_ByTitle() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.No' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.No); + + // Set 'FieldStorage.Yes' to store the original content of field 'Content' + // in the index + Stores.Add(x => x.Content, FieldStorage.Yes); + + // => No analyzer will process field 'Content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public class AnalyzerDefinition +\{ + // Name of the analyzer + public string Name \{ get; set; \} + + // C# source-code of the analyzer + public string Code \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`// Define the put analyzer operation: +var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition +\{ + // The name must be same as the analyzer's class name + Name = "MyAnalyzer", + + Code = @" + using System.IO; + using Lucene.Net.Analysis; + using Lucene.Net.Analysis.Standard; + + namespace MyAnalyzer + \{ + public class MyAnalyzer : Lucene.Net.Analysis.Analyzer + \{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + throw new CodeOmitted(); + \} + \} + \}" +\}); + +// Deploy the analyzer: +store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-7.0/indexes/_using-analyzers-java.mdx b/versioned_docs/version-7.0/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-7.0/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_using-analyzers-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_using-analyzers-nodejs.mdx new file mode 100644 index 0000000000..6d96e400e2 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-analyzers-nodejs.mdx @@ -0,0 +1,655 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + +1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + +2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + set the `analyze()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content + })\`; + + // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer + this.analyze("tags", "SimpleAnalyzer"); + + // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer + this.analyze("content", "Raven.Sample.SnowballAnalyzer"); + } +} +`} + + + + +{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); +builder.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content +})\`; +builder.analyzersStrings["tags"] = "SimpleAnalyzer"; +builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; + +await store.maintenance + .send(new PutIndexesOperation( + builder.toIndexDefinition(store.conventions))); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `Exact` + * `Search` + * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Search' on index-field 'content' + this.index("content", "Search"); + + // => Index-field 'content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FirstName = employee.FirstName " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Exact' on index-field 'FirstName' + this.index("FirstName", "Exact"); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName" + + "\})"; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'No' on index-field 'content' + this.index("content", "No"); + + // Set 'Yes' to store the original content of field 'content' in the index + this.store("content", "Yes"); + + // => No analyzer will process field 'content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`const analyzerDefinition = \{ + name: "analyzerName", + code: "code" +\}; +`} + + + +| Parameter | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`const analyzerDefinition = \{ + name: "MyAnalyzer", + code: "using System.IO;\\n" + + "using Lucene.Net.Analysis;\\n" + + "using Lucene.Net.Analysis.Standard;\\n" + + "\\n" + + "namespace MyAnalyzer\\n" + + "\{\\n" + + " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + + " \{\\n" + + " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + + " \{\\n" + + " throw new CodeOmitted();\\n" + + " \}\\n" + + " \}\\n" + + "\}\\n" +\}; + +await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..8484315d55 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,550 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..0fd89b32ac --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,480 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..146a2f25c5 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-php.mdx b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..690dfe4bd2 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,560 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-python.mdx b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..274c90ba20 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,512 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_using-term-vectors-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/versioned_docs/version-7.0/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-7.0/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-7.0/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-7.0/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-7.0/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/content/_what-are-indexes-csharp.mdx b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..947039be10 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_what-are-indexes-java.mdx b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..8c5adfb5e7 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_what-are-indexes-nodejs.mdx b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_what-are-indexes-php.mdx b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.0/indexes/content/_what-are-indexes-python.mdx b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/versioned_docs/version-7.0/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.0/indexes/creating-and-deploying.mdx b/versioned_docs/version-7.0/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/versioned_docs/version-7.0/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-7.0/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/extending-indexes.mdx b/versioned_docs/version-7.0/indexes/extending-indexes.mdx index a45e5b92c4..948debd159 100644 --- a/versioned_docs/version-7.0/indexes/extending-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-basics.mdx b/versioned_docs/version-7.0/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-7.0/indexes/indexing-basics.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-compare-exchange-values.mdx b/versioned_docs/version-7.0/indexes/indexing-compare-exchange-values.mdx index dedad857b3..e7c98f086f 100644 --- a/versioned_docs/version-7.0/indexes/indexing-compare-exchange-values.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-compare-exchange-values.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCompareExchangeValuesCsharp from './_indexing-compare-exchange-values-csharp.mdx'; -import IndexingCompareExchangeValuesJava from './_indexing-compare-exchange-values-java.mdx'; -import IndexingCompareExchangeValuesNodejs from './_indexing-compare-exchange-values-nodejs.mdx'; +import IndexingCompareExchangeValuesCsharp from './content/_indexing-compare-exchange-values-csharp.mdx'; +import IndexingCompareExchangeValuesJava from './content/_indexing-compare-exchange-values-java.mdx'; +import IndexingCompareExchangeValuesNodejs from './content/_indexing-compare-exchange-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-7.0/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/versioned_docs/version-7.0/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-7.0/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-7.0/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-metadata.mdx b/versioned_docs/version-7.0/indexes/indexing-metadata.mdx index 6c81cc4ad3..9af5ee1d1d 100644 --- a/versioned_docs/version-7.0/indexes/indexing-metadata.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingMetadataCsharp from './_indexing-metadata-csharp.mdx'; -import IndexingMetadataJava from './_indexing-metadata-java.mdx'; -import IndexingMetadataPython from './_indexing-metadata-python.mdx'; -import IndexingMetadataPhp from './_indexing-metadata-php.mdx'; -import IndexingMetadataNodejs from './_indexing-metadata-nodejs.mdx'; +import IndexingMetadataCsharp from './content/_indexing-metadata-csharp.mdx'; +import IndexingMetadataJava from './content/_indexing-metadata-java.mdx'; +import IndexingMetadataPython from './content/_indexing-metadata-python.mdx'; +import IndexingMetadataPhp from './content/_indexing-metadata-php.mdx'; +import IndexingMetadataNodejs from './content/_indexing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-nested-data.mdx b/versioned_docs/version-7.0/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/versioned_docs/version-7.0/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-7.0/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/versioned_docs/version-7.0/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-related-documents.mdx b/versioned_docs/version-7.0/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/versioned_docs/version-7.0/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/indexing-spatial-data.mdx b/versioned_docs/version-7.0/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/versioned_docs/version-7.0/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-7.0/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/javascript-indexes.mdx b/versioned_docs/version-7.0/indexes/javascript-indexes.mdx index c3823fd587..d5a516c218 100644 --- a/versioned_docs/version-7.0/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-7.0/indexes/map-indexes.mdx b/versioned_docs/version-7.0/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/versioned_docs/version-7.0/indexes/map-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/map-reduce-indexes.mdx b/versioned_docs/version-7.0/indexes/map-reduce-indexes.mdx index b783b56532..eb29118146 100644 --- a/versioned_docs/version-7.0/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/multi-map-indexes.mdx b/versioned_docs/version-7.0/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/versioned_docs/version-7.0/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/number-type-conversion.mdx b/versioned_docs/version-7.0/indexes/number-type-conversion.mdx index c0b91b60f3..46a942da8f 100644 --- a/versioned_docs/version-7.0/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-7.0/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21157296fd..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1052 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-7.0/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-7.0/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_faceted-search-php.mdx b/versioned_docs/version-7.0/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_faceted-search-python.mdx b/versioned_docs/version-7.0/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 7bba94c71c..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,783 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_paging-java.mdx b/versioned_docs/version-7.0/indexes/querying/_paging-java.mdx deleted file mode 100644 index c69b33f0d7..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,307 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 253f2a5e98..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance -**Better performance**: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -**Performance hints**: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_paging-php.mdx b/versioned_docs/version-7.0/indexes/querying/_paging-php.mdx deleted file mode 100644 index 596a8e12fd..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,688 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_paging-python.mdx b/versioned_docs/version-7.0/indexes/querying/_paging-python.mdx deleted file mode 100644 index 3ca064b801..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,431 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_spatial-java.mdx b/versioned_docs/version-7.0/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_suggestions-php.mdx b/versioned_docs/version-7.0/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_suggestions-python.mdx b/versioned_docs/version-7.0/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/versioned_docs/version-7.0/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.0/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_distinct-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_exploration-queries-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_exploration-queries-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_exploration-queries-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_exploration-queries-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_exploration-queries-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_exploration-queries-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_exploration-queries-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..7adddea4b9 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1052 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_filtering-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_filtering-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_filtering-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_filtering-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_filtering-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_highlighting-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_highlighting-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_highlighting-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_highlighting-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_highlighting-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_highlighting-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_include-explanations-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_include-explanations-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_include-explanations-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_include-explanations-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_intersection-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_intersection-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_intersection-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_intersection-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_intersection-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_intersection-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_intersection-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_morelikethis-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_morelikethis-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_morelikethis-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_morelikethis-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_morelikethis-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_morelikethis-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..8f8b1df9c8 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,783 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..0e9fbc3606 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,307 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..8f97f74d19 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance +**Better performance**: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +**Performance hints**: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_paging-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..9a3a910996 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,688 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_paging-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..a357c96094 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,431 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_projections-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_projections-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_projections-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_projections-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_projections-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_projections-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_projections-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_projections-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_projections-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_projections-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_query-index-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_query-index-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_query-index-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_query-index-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_query-index-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_query-index-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_query-index-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_searching-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_searching-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_searching-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_searching-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_searching-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_searching-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_searching-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_searching-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_searching-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_searching-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_sorting-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_sorting-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_sorting-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_sorting-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_sorting-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_sorting-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_sorting-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-7.0/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_spatial-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_spatial-php.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_spatial-php.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/_spatial-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_spatial-python.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_spatial-python.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_suggestions-php.mdx b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/content/_suggestions-python.mdx b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/versioned_docs/version-7.0/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.0/indexes/querying/_vector-search-csharp.mdx b/versioned_docs/version-7.0/indexes/querying/content/_vector-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/indexes/querying/_vector-search-csharp.mdx rename to versioned_docs/version-7.0/indexes/querying/content/_vector-search-csharp.mdx diff --git a/versioned_docs/version-7.0/indexes/querying/distinct.mdx b/versioned_docs/version-7.0/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-7.0/indexes/querying/distinct.mdx +++ b/versioned_docs/version-7.0/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/exploration-queries.mdx b/versioned_docs/version-7.0/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/versioned_docs/version-7.0/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-7.0/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/faceted-search.mdx b/versioned_docs/version-7.0/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/versioned_docs/version-7.0/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-7.0/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/filtering.mdx b/versioned_docs/version-7.0/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/versioned_docs/version-7.0/indexes/querying/filtering.mdx +++ b/versioned_docs/version-7.0/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/highlighting.mdx b/versioned_docs/version-7.0/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/versioned_docs/version-7.0/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-7.0/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/include-explanations.mdx b/versioned_docs/version-7.0/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/versioned_docs/version-7.0/indexes/querying/include-explanations.mdx +++ b/versioned_docs/version-7.0/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/intersection.mdx b/versioned_docs/version-7.0/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/versioned_docs/version-7.0/indexes/querying/intersection.mdx +++ b/versioned_docs/version-7.0/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/morelikethis.mdx b/versioned_docs/version-7.0/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/versioned_docs/version-7.0/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-7.0/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/paging.mdx b/versioned_docs/version-7.0/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/versioned_docs/version-7.0/indexes/querying/paging.mdx +++ b/versioned_docs/version-7.0/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/projections.mdx b/versioned_docs/version-7.0/indexes/querying/projections.mdx index 6a24194fc0..779a07b48b 100644 --- a/versioned_docs/version-7.0/indexes/querying/projections.mdx +++ b/versioned_docs/version-7.0/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/query-index.mdx b/versioned_docs/version-7.0/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/versioned_docs/version-7.0/indexes/querying/query-index.mdx +++ b/versioned_docs/version-7.0/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/searching.mdx b/versioned_docs/version-7.0/indexes/querying/searching.mdx index 9f0b5aebc1..9b88c79e82 100644 --- a/versioned_docs/version-7.0/indexes/querying/searching.mdx +++ b/versioned_docs/version-7.0/indexes/querying/searching.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/sorting.mdx b/versioned_docs/version-7.0/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/versioned_docs/version-7.0/indexes/querying/sorting.mdx +++ b/versioned_docs/version-7.0/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/spatial.mdx b/versioned_docs/version-7.0/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/versioned_docs/version-7.0/indexes/querying/spatial.mdx +++ b/versioned_docs/version-7.0/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/suggestions.mdx b/versioned_docs/version-7.0/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/versioned_docs/version-7.0/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-7.0/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/querying/vector-search.mdx b/versioned_docs/version-7.0/indexes/querying/vector-search.mdx index 696138dc56..2d9834abaa 100644 --- a/versioned_docs/version-7.0/indexes/querying/vector-search.mdx +++ b/versioned_docs/version-7.0/indexes/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.0/indexes/sorting-and-collation.mdx b/versioned_docs/version-7.0/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-7.0/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-7.0/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-7.0/indexes/stale-indexes.mdx b/versioned_docs/version-7.0/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-7.0/indexes/stale-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/storing-data-in-index.mdx b/versioned_docs/version-7.0/indexes/storing-data-in-index.mdx index d14d9b3662..9fa4d96090 100644 --- a/versioned_docs/version-7.0/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-7.0/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "python", "php", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; diff --git a/versioned_docs/version-7.0/indexes/using-analyzers.mdx b/versioned_docs/version-7.0/indexes/using-analyzers.mdx index ff0865eb70..cfaf304f2e 100644 --- a/versioned_docs/version-7.0/indexes/using-analyzers.mdx +++ b/versioned_docs/version-7.0/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/using-dynamic-fields.mdx b/versioned_docs/version-7.0/indexes/using-dynamic-fields.mdx index 010c89de9b..fe92642e46 100644 --- a/versioned_docs/version-7.0/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-7.0/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/indexes/using-term-vectors.mdx b/versioned_docs/version-7.0/indexes/using-term-vectors.mdx index 94ef7ada0b..819e006fd0 100644 --- a/versioned_docs/version-7.0/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-7.0/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/versioned_docs/version-7.0/indexes/what-are-indexes.mdx b/versioned_docs/version-7.0/indexes/what-are-indexes.mdx index b05d8422dc..8821d797d4 100644 --- a/versioned_docs/version-7.0/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-7.0/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/server/_embedded-csharp.mdx b/versioned_docs/version-7.0/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/server/_embedded-csharp.mdx rename to versioned_docs/version-7.0/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-7.0/server/_embedded-java.mdx b/versioned_docs/version-7.0/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-7.0/server/_embedded-java.mdx rename to versioned_docs/version-7.0/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-7.0/server/embedded.mdx b/versioned_docs/version-7.0/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/versioned_docs/version-7.0/server/embedded.mdx +++ b/versioned_docs/version-7.0/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-7.0/server/extensions/_refresh-csharp.mdx b/versioned_docs/version-7.0/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/versioned_docs/version-7.0/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-7.0/server/extensions/_expiration-csharp.mdx b/versioned_docs/version-7.0/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/server/extensions/_expiration-csharp.mdx rename to versioned_docs/version-7.0/server/extensions/content/_expiration-csharp.mdx diff --git a/versioned_docs/version-7.0/server/extensions/content/_refresh-csharp.mdx b/versioned_docs/version-7.0/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/versioned_docs/version-7.0/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-7.0/server/extensions/expiration.mdx b/versioned_docs/version-7.0/server/extensions/expiration.mdx index 81180dfe2c..3c84777ab1 100644 --- a/versioned_docs/version-7.0/server/extensions/expiration.mdx +++ b/versioned_docs/version-7.0/server/extensions/expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; diff --git a/versioned_docs/version-7.0/server/extensions/refresh.mdx b/versioned_docs/version-7.0/server/extensions/refresh.mdx index 9dc2ef60b8..2cd56d007a 100644 --- a/versioned_docs/version-7.0/server/extensions/refresh.mdx +++ b/versioned_docs/version-7.0/server/extensions/refresh.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; diff --git a/versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx b/versioned_docs/version-7.0/server/kb/content/_document-identifier-generation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx rename to versioned_docs/version-7.0/server/kb/content/_document-identifier-generation-csharp.mdx diff --git a/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx b/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx index 6bec153835..46a987ed21 100644 --- a/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx +++ b/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; +import DocumentIDsCsharp from './content/_document-identifier-generation-csharp.mdx'; diff --git a/versioned_docs/version-7.0/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-7.0/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-7.0/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-7.0/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-7.0/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.0/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-7.0/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-7.0/server/storage/documents-compression.mdx b/versioned_docs/version-7.0/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-7.0/server/storage/documents-compression.mdx +++ b/versioned_docs/version-7.0/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/start/_test-driver-csharp.mdx b/versioned_docs/version-7.0/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-7.0/start/_test-driver-csharp.mdx rename to versioned_docs/version-7.0/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-7.0/start/_test-driver-java.mdx b/versioned_docs/version-7.0/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-7.0/start/_test-driver-java.mdx rename to versioned_docs/version-7.0/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-csharp.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-nodejs.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/versioned_docs/version-7.0/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/_overview-csharp.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/versioned_docs/version-7.0/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/_overview-nodejs.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index e9abea53ff..0000000000 --- a/versioned_docs/version-7.0/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-csharp.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/versioned_docs/version-7.0/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-csharp.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-nodejs.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..a6bf58b4c8 --- /dev/null +++ b/versioned_docs/version-7.0/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/existing-project.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/versioned_docs/version-7.0/start/guides/azure-functions/existing-project.mdx +++ b/versioned_docs/version-7.0/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/start/guides/azure-functions/overview.mdx b/versioned_docs/version-7.0/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/versioned_docs/version-7.0/start/guides/azure-functions/overview.mdx +++ b/versioned_docs/version-7.0/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.0/start/test-driver.mdx b/versioned_docs/version-7.0/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/versioned_docs/version-7.0/start/test-driver.mdx +++ b/versioned_docs/version-7.0/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx b/versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-csharp.mdx rename to versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx b/versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-java.mdx rename to versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-java.mdx diff --git a/versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx b/versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/bulk-insert/_how-to-work-with-bulk-insert-operation-nodejs.mdx rename to versioned_docs/version-7.1/client-api/bulk-insert/content/_how-to-work-with-bulk-insert-operation-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx b/versioned_docs/version-7.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx index c5cfb3ded2..42f2434b24 100644 --- a/versioned_docs/version-7.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx +++ b/versioned_docs/version-7.1/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithBulkInsertOperationCsharp from './_how-to-work-with-bulk-insert-operation-csharp.mdx'; -import HowToWorkWithBulkInsertOperationJava from './_how-to-work-with-bulk-insert-operation-java.mdx'; -import HowToWorkWithBulkInsertOperationNodejs from './_how-to-work-with-bulk-insert-operation-nodejs.mdx'; +import HowToWorkWithBulkInsertOperationCsharp from './content/_how-to-work-with-bulk-insert-operation-csharp.mdx'; +import HowToWorkWithBulkInsertOperationJava from './content/_how-to-work-with-bulk-insert-operation-java.mdx'; +import HowToWorkWithBulkInsertOperationNodejs from './content/_how-to-work-with-bulk-insert-operation-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-counter-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-counter-changes-java.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-counter-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-java.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-document-changes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-document-changes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-java.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-index-changes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-index-changes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-java.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-operation-changes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-operation-changes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_how-to-subscribe-to-time-series-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_how-to-subscribe-to-time-series-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-csharp.mdx b/versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-csharp.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-java.mdx b/versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-java.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-java.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-nodejs.mdx b/versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/changes/_what-is-changes-api-nodejs.mdx rename to versioned_docs/version-7.1/client-api/changes/content/_what-is-changes-api-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx index 69388129ac..66a0ff166f 100644 --- a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx +++ b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-counter-changes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToCounterChangesCsharp from './_how-to-subscribe-to-counter-changes-csharp.mdx'; -import HowToSubscribeToCounterChangesJava from './_how-to-subscribe-to-counter-changes-java.mdx'; +import HowToSubscribeToCounterChangesCsharp from './content/_how-to-subscribe-to-counter-changes-csharp.mdx'; +import HowToSubscribeToCounterChangesJava from './content/_how-to-subscribe-to-counter-changes-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-document-changes.mdx b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-document-changes.mdx index 679dc3b5d7..0b5fec7da8 100644 --- a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-document-changes.mdx +++ b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-document-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToDocumentChangesCsharp from './_how-to-subscribe-to-document-changes-csharp.mdx'; -import HowToSubscribeToDocumentChangesJava from './_how-to-subscribe-to-document-changes-java.mdx'; -import HowToSubscribeToDocumentChangesNodejs from './_how-to-subscribe-to-document-changes-nodejs.mdx'; +import HowToSubscribeToDocumentChangesCsharp from './content/_how-to-subscribe-to-document-changes-csharp.mdx'; +import HowToSubscribeToDocumentChangesJava from './content/_how-to-subscribe-to-document-changes-java.mdx'; +import HowToSubscribeToDocumentChangesNodejs from './content/_how-to-subscribe-to-document-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-index-changes.mdx b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-index-changes.mdx index a90b61cfb1..2967b2c4b3 100644 --- a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-index-changes.mdx +++ b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-index-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToIndexChangesCsharp from './_how-to-subscribe-to-index-changes-csharp.mdx'; -import HowToSubscribeToIndexChangesJava from './_how-to-subscribe-to-index-changes-java.mdx'; -import HowToSubscribeToIndexChangesNodejs from './_how-to-subscribe-to-index-changes-nodejs.mdx'; +import HowToSubscribeToIndexChangesCsharp from './content/_how-to-subscribe-to-index-changes-csharp.mdx'; +import HowToSubscribeToIndexChangesJava from './content/_how-to-subscribe-to-index-changes-java.mdx'; +import HowToSubscribeToIndexChangesNodejs from './content/_how-to-subscribe-to-index-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx index ea55dc80b4..bbfc7cbf2f 100644 --- a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx +++ b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-operation-changes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToOperationChangesCsharp from './_how-to-subscribe-to-operation-changes-csharp.mdx'; -import HowToSubscribeToOperationChangesJava from './_how-to-subscribe-to-operation-changes-java.mdx'; -import HowToSubscribeToOperationChangesNodejs from './_how-to-subscribe-to-operation-changes-nodejs.mdx'; +import HowToSubscribeToOperationChangesCsharp from './content/_how-to-subscribe-to-operation-changes-csharp.mdx'; +import HowToSubscribeToOperationChangesJava from './content/_how-to-subscribe-to-operation-changes-java.mdx'; +import HowToSubscribeToOperationChangesNodejs from './content/_how-to-subscribe-to-operation-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx index 7411085ff4..9343c9313a 100644 --- a/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx +++ b/versioned_docs/version-7.1/client-api/changes/how-to-subscribe-to-time-series-changes.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSubscribeToTimeSeriesChangesCsharp from './_how-to-subscribe-to-time-series-changes-csharp.mdx'; +import HowToSubscribeToTimeSeriesChangesCsharp from './content/_how-to-subscribe-to-time-series-changes-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/changes/what-is-changes-api.mdx b/versioned_docs/version-7.1/client-api/changes/what-is-changes-api.mdx index f1a5ef4834..40b902f1c5 100644 --- a/versioned_docs/version-7.1/client-api/changes/what-is-changes-api.mdx +++ b/versioned_docs/version-7.1/client-api/changes/what-is-changes-api.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsChangesApiCsharp from './_what-is-changes-api-csharp.mdx'; -import WhatIsChangesApiJava from './_what-is-changes-api-java.mdx'; -import WhatIsChangesApiNodejs from './_what-is-changes-api-nodejs.mdx'; +import WhatIsChangesApiCsharp from './content/_what-is-changes-api-csharp.mdx'; +import WhatIsChangesApiJava from './content/_what-is-changes-api-java.mdx'; +import WhatIsChangesApiNodejs from './content/_what-is-changes-api-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx b/versioned_docs/version-7.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/cluster/_document-conflicts-in-client-side-csharp.mdx rename to versioned_docs/version-7.1/client-api/cluster/content/_document-conflicts-in-client-side-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx b/versioned_docs/version-7.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/cluster/_document-conflicts-in-client-side-java.mdx rename to versioned_docs/version-7.1/client-api/cluster/content/_document-conflicts-in-client-side-java.mdx diff --git a/versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx b/versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-csharp.mdx rename to versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx b/versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-java.mdx rename to versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-java.mdx diff --git a/versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx b/versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/cluster/_how-client-integrates-with-replication-and-cluster-nodejs.mdx rename to versioned_docs/version-7.1/client-api/cluster/content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/cluster/document-conflicts-in-client-side.mdx b/versioned_docs/version-7.1/client-api/cluster/document-conflicts-in-client-side.mdx index 6827093f77..15333b34bc 100644 --- a/versioned_docs/version-7.1/client-api/cluster/document-conflicts-in-client-side.mdx +++ b/versioned_docs/version-7.1/client-api/cluster/document-conflicts-in-client-side.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentConflictsInClientSideCsharp from './_document-conflicts-in-client-side-csharp.mdx'; -import DocumentConflictsInClientSideJava from './_document-conflicts-in-client-side-java.mdx'; +import DocumentConflictsInClientSideCsharp from './content/_document-conflicts-in-client-side-csharp.mdx'; +import DocumentConflictsInClientSideJava from './content/_document-conflicts-in-client-side-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx b/versioned_docs/version-7.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx index 888e9bf95f..dc549bd709 100644 --- a/versioned_docs/version-7.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx +++ b/versioned_docs/version-7.1/client-api/cluster/how-client-integrates-with-replication-and-cluster.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowClientIntegratesWithReplicationAndClusterCsharp from './_how-client-integrates-with-replication-and-cluster-csharp.mdx'; -import HowClientIntegratesWithReplicationAndClusterJava from './_how-client-integrates-with-replication-and-cluster-java.mdx'; -import HowClientIntegratesWithReplicationAndClusterNodejs from './_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; +import HowClientIntegratesWithReplicationAndClusterCsharp from './content/_how-client-integrates-with-replication-and-cluster-csharp.mdx'; +import HowClientIntegratesWithReplicationAndClusterJava from './content/_how-client-integrates-with-replication-and-cluster-java.mdx'; +import HowClientIntegratesWithReplicationAndClusterNodejs from './content/_how-client-integrates-with-replication-and-cluster-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx b/versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-csharp.mdx rename to versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx b/versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-java.mdx rename to versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-java.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx b/versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/batches/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx rename to versioned_docs/version-7.1/client-api/commands/batches/content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx b/versioned_docs/version-7.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx index 668d999b7d..5c6923b919 100644 --- a/versioned_docs/version-7.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx +++ b/versioned_docs/version-7.1/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToSendMultipleCommandsUsingABatchCsharp from './_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; -import HowToSendMultipleCommandsUsingABatchJava from './_how-to-send-multiple-commands-using-a-batch-java.mdx'; -import HowToSendMultipleCommandsUsingABatchNodejs from './_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; +import HowToSendMultipleCommandsUsingABatchCsharp from './content/_how-to-send-multiple-commands-using-a-batch-csharp.mdx'; +import HowToSendMultipleCommandsUsingABatchJava from './content/_how-to-send-multiple-commands-using-a-batch-java.mdx'; +import HowToSendMultipleCommandsUsingABatchNodejs from './content/_how-to-send-multiple-commands-using-a-batch-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/commands/_overview-csharp.mdx b/versioned_docs/version-7.1/client-api/commands/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/_overview-csharp.mdx rename to versioned_docs/version-7.1/client-api/commands/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/_overview-java.mdx b/versioned_docs/version-7.1/client-api/commands/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/_overview-java.mdx rename to versioned_docs/version-7.1/client-api/commands/content/_overview-java.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/_overview-nodejs.mdx b/versioned_docs/version-7.1/client-api/commands/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/_overview-nodejs.mdx rename to versioned_docs/version-7.1/client-api/commands/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_delete-csharp.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_delete-csharp.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_delete-java.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_delete-java.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_delete-java.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_delete-nodejs.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_delete-nodejs.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_delete-php.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_delete-php.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_delete-php.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_delete-python.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_delete-python.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_delete-python.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_get-csharp.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_get-csharp.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_get-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_get-java.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_get-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_get-java.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_get-java.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_get-nodejs.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_get-nodejs.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_get-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_get-php.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_get-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_get-php.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_get-php.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_get-python.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_get-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_get-python.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_get-python.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_put-csharp.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_put-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_put-csharp.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_put-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_put-java.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_put-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_put-java.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_put-java.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_put-nodejs.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_put-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_put-nodejs.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_put-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_put-php.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_put-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_put-php.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_put-php.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/_put-python.mdx b/versioned_docs/version-7.1/client-api/commands/documents/content/_put-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/commands/documents/_put-python.mdx rename to versioned_docs/version-7.1/client-api/commands/documents/content/_put-python.mdx diff --git a/versioned_docs/version-7.1/client-api/commands/documents/delete.mdx b/versioned_docs/version-7.1/client-api/commands/documents/delete.mdx index 61091b815c..a88bb5f5db 100644 --- a/versioned_docs/version-7.1/client-api/commands/documents/delete.mdx +++ b/versioned_docs/version-7.1/client-api/commands/documents/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/commands/documents/get.mdx b/versioned_docs/version-7.1/client-api/commands/documents/get.mdx index 1e303a3f73..325076a4dc 100644 --- a/versioned_docs/version-7.1/client-api/commands/documents/get.mdx +++ b/versioned_docs/version-7.1/client-api/commands/documents/get.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetJava from './_get-java.mdx'; -import GetPython from './_get-python.mdx'; -import GetPhp from './_get-php.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetJava from './content/_get-java.mdx'; +import GetPython from './content/_get-python.mdx'; +import GetPhp from './content/_get-php.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/commands/documents/put.mdx b/versioned_docs/version-7.1/client-api/commands/documents/put.mdx index ee9e70143c..9c8ba28480 100644 --- a/versioned_docs/version-7.1/client-api/commands/documents/put.mdx +++ b/versioned_docs/version-7.1/client-api/commands/documents/put.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCsharp from './_put-csharp.mdx'; -import PutJava from './_put-java.mdx'; -import PutPython from './_put-python.mdx'; -import PutPhp from './_put-php.mdx'; -import PutNodejs from './_put-nodejs.mdx'; +import PutCsharp from './content/_put-csharp.mdx'; +import PutJava from './content/_put-java.mdx'; +import PutPython from './content/_put-python.mdx'; +import PutPhp from './content/_put-php.mdx'; +import PutNodejs from './content/_put-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/commands/overview.mdx b/versioned_docs/version-7.1/client-api/commands/overview.mdx index dd0aca1a6c..744fb40071 100644 --- a/versioned_docs/version-7.1/client-api/commands/overview.mdx +++ b/versioned_docs/version-7.1/client-api/commands/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_conventions-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_conventions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_conventions-nodejs.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_conventions-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/_deserialization-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_deserialization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_deserialization-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_deserialization-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/_deserialization-java.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_deserialization-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_deserialization-java.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_deserialization-java.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/_serialization-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_serialization-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/_serialization-java.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_serialization-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/_serialization-java.mdx rename to versioned_docs/version-7.1/client-api/configuration/content/_serialization-java.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/conventions.mdx b/versioned_docs/version-7.1/client-api/configuration/conventions.mdx index 9f37014e79..0732a9c24c 100644 --- a/versioned_docs/version-7.1/client-api/configuration/conventions.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/conventions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConventionsCsharp from './_conventions-csharp.mdx'; -import ConventionsNodejs from './_conventions-nodejs.mdx'; +import ConventionsCsharp from './content/_conventions-csharp.mdx'; +import ConventionsNodejs from './content/_conventions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/deserialization.mdx b/versioned_docs/version-7.1/client-api/configuration/deserialization.mdx index 62b4a8bdec..95ddcf7384 100644 --- a/versioned_docs/version-7.1/client-api/configuration/deserialization.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/deserialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationCsharp from './_deserialization-csharp.mdx'; -import DeserializationJava from './_deserialization-java.mdx'; +import DeserializationCsharp from './content/_deserialization-csharp.mdx'; +import DeserializationJava from './content/_deserialization-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-java.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-java.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-java.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-nodejs.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_global-nodejs.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_global-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-java.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-java.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-java.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/identifier-generation/_type-specific-nodejs.mdx rename to versioned_docs/version-7.1/client-api/configuration/identifier-generation/content/_type-specific-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/global.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/global.mdx index 366253e08a..fd2a05d6bb 100644 --- a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/global.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/global.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GlobalCsharp from './_global-csharp.mdx'; -import GlobalJava from './_global-java.mdx'; -import GlobalNodejs from './_global-nodejs.mdx'; +import GlobalCsharp from './content/_global-csharp.mdx'; +import GlobalJava from './content/_global-java.mdx'; +import GlobalNodejs from './content/_global-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/type-specific.mdx b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/type-specific.mdx index b9619f7642..f5fbdccf25 100644 --- a/versioned_docs/version-7.1/client-api/configuration/identifier-generation/type-specific.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/identifier-generation/type-specific.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TypeSpecificCsharp from './_type-specific-csharp.mdx'; -import TypeSpecificJava from './_type-specific-java.mdx'; -import TypeSpecificNodejs from './_type-specific-nodejs.mdx'; +import TypeSpecificCsharp from './content/_type-specific-csharp.mdx'; +import TypeSpecificJava from './content/_type-specific-java.mdx'; +import TypeSpecificNodejs from './content/_type-specific-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-nodejs.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-php.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-php.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-php.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-python.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_load-balance-behavior-python.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_load-balance-behavior-python.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-csharp.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-nodejs.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-php.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-php.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-php.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-python.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/configuration/load-balance/_read-balance-behavior-python.mdx rename to versioned_docs/version-7.1/client-api/configuration/load-balance/content/_read-balance-behavior-python.mdx diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/load-balance-behavior.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/load-balance-behavior.mdx index 49651fed37..2f8240d8f9 100644 --- a/versioned_docs/version-7.1/client-api/configuration/load-balance/load-balance-behavior.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/load-balance/load-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadBalanceBehaviorCsharp from './_load-balance-behavior-csharp.mdx'; -import LoadBalanceBehaviorPython from './_load-balance-behavior-python.mdx'; -import LoadBalanceBehaviorPhp from './_load-balance-behavior-php.mdx'; -import LoadBalanceBehaviorNodejs from './_load-balance-behavior-nodejs.mdx'; +import LoadBalanceBehaviorCsharp from './content/_load-balance-behavior-csharp.mdx'; +import LoadBalanceBehaviorPython from './content/_load-balance-behavior-python.mdx'; +import LoadBalanceBehaviorPhp from './content/_load-balance-behavior-php.mdx'; +import LoadBalanceBehaviorNodejs from './content/_load-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/load-balance/read-balance-behavior.mdx b/versioned_docs/version-7.1/client-api/configuration/load-balance/read-balance-behavior.mdx index b530c2a5b9..faed614ed0 100644 --- a/versioned_docs/version-7.1/client-api/configuration/load-balance/read-balance-behavior.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/load-balance/read-balance-behavior.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReadBalanceBehaviorCsharp from './_read-balance-behavior-csharp.mdx'; -import ReadBalanceBehaviorPython from './_read-balance-behavior-python.mdx'; -import ReadBalanceBehaviorPhp from './_read-balance-behavior-php.mdx'; -import ReadBalanceBehaviorNodejs from './_read-balance-behavior-nodejs.mdx'; +import ReadBalanceBehaviorCsharp from './content/_read-balance-behavior-csharp.mdx'; +import ReadBalanceBehaviorPython from './content/_read-balance-behavior-python.mdx'; +import ReadBalanceBehaviorPhp from './content/_read-balance-behavior-php.mdx'; +import ReadBalanceBehaviorNodejs from './content/_read-balance-behavior-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/configuration/serialization.mdx b/versioned_docs/version-7.1/client-api/configuration/serialization.mdx index b772bb51fb..6b6a9e51df 100644 --- a/versioned_docs/version-7.1/client-api/configuration/serialization.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/serialization.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SerializationCsharp from './_serialization-csharp.mdx'; -import SerializationJava from './_serialization-java.mdx'; +import SerializationCsharp from './content/_serialization-csharp.mdx'; +import SerializationJava from './content/_serialization-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/_creating-document-store-csharp.mdx b/versioned_docs/version-7.1/client-api/content/_creating-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_creating-document-store-csharp.mdx rename to versioned_docs/version-7.1/client-api/content/_creating-document-store-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/_creating-document-store-java.mdx b/versioned_docs/version-7.1/client-api/content/_creating-document-store-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_creating-document-store-java.mdx rename to versioned_docs/version-7.1/client-api/content/_creating-document-store-java.mdx diff --git a/versioned_docs/version-7.1/client-api/_creating-document-store-nodejs.mdx b/versioned_docs/version-7.1/client-api/content/_creating-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_creating-document-store-nodejs.mdx rename to versioned_docs/version-7.1/client-api/content/_creating-document-store-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/_net-client-versions-csharp.mdx b/versioned_docs/version-7.1/client-api/content/_net-client-versions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_net-client-versions-csharp.mdx rename to versioned_docs/version-7.1/client-api/content/_net-client-versions-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-csharp.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-java.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-java.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-java.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-authentication-and-authorization-nodejs.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-authentication-and-authorization-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-default-database-csharp.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-default-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-default-database-csharp.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-default-database-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-default-database-java.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-default-database-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-default-database-java.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-default-database-java.mdx diff --git a/versioned_docs/version-7.1/client-api/_setting-up-default-database-nodejs.mdx b/versioned_docs/version-7.1/client-api/content/_setting-up-default-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_setting-up-default-database-nodejs.mdx rename to versioned_docs/version-7.1/client-api/content/_setting-up-default-database-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/_what-is-a-document-store-csharp.mdx b/versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_what-is-a-document-store-csharp.mdx rename to versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/_what-is-a-document-store-java.mdx b/versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_what-is-a-document-store-java.mdx rename to versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-java.mdx diff --git a/versioned_docs/version-7.1/client-api/_what-is-a-document-store-nodejs.mdx b/versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/_what-is-a-document-store-nodejs.mdx rename to versioned_docs/version-7.1/client-api/content/_what-is-a-document-store-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/creating-document-store.mdx b/versioned_docs/version-7.1/client-api/creating-document-store.mdx index 10f44109e2..5042d9c97b 100644 --- a/versioned_docs/version-7.1/client-api/creating-document-store.mdx +++ b/versioned_docs/version-7.1/client-api/creating-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingDocumentStoreCsharp from './_creating-document-store-csharp.mdx'; -import CreatingDocumentStoreJava from './_creating-document-store-java.mdx'; -import CreatingDocumentStoreNodejs from './_creating-document-store-nodejs.mdx'; +import CreatingDocumentStoreCsharp from './content/_creating-document-store-csharp.mdx'; +import CreatingDocumentStoreJava from './content/_creating-document-store-java.mdx'; +import CreatingDocumentStoreNodejs from './content/_creating-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx deleted file mode 100644 index cd09e4587d..0000000000 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-csharp.mdx +++ /dev/null @@ -1,160 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - -## Data subscription consumption - -* Data subscriptions are consumed by clients, called **Subscription Workers**. -* You can determine whether workers would be able to connect a subscription - [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). -* A worker that connects to a data subscription receives a batch of documents, and gets to process it. - Depending on the code that the client provided the worker with, processing can take from seconds to hours. - When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server-side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -* The processing progress is persisted on the server and therefore the subscription - task can be paused and resumed from the last point it was stopped. -* The persistence mechanism also ensures that no documents are missed even in the - presence of failure, whether it's client-side related, communication, or any other disaster. -* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. - In the case of a node failure, the processing can be automatically failed over to another node. -* The usage of **Change Vectors** allows us to continue from a point that is close to - the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents in a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license, the cluster will automatically reassign the work to another node. - - -* The status of the TCP connection is also used to determine the "state" of the worker process. - If the subscription and its workers implement a - [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) - strategy, as long as the connection is alive the server will not allow - other clients to consume the subscription. -* The TCP connection is kept alive and monitored using "heartbeat" messages. - If the connection is found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifespan of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -You can use a **Subscription Worker Strategy** to determine whether multiple -workers of the same subscription can connect to it one by one, or **concurrently**. - -* **One Worker Per Subscription Strategies** - The one-worker-per-subscription strategies allow workers of the same subscription - to connect to it **one worker at a time**, with different strategies to support various - inter-worker scenarios. - * One worker is allowed to take the place of another in the processing of a subscription. - Thanks to subscriptions persistence, the worker will be able to continue the work - starting at the point its predecessor got to. - * You can also configure a worker to wait for an existing connection to fail and take - its place, or to force an existing connection to close. - * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). - -* **Concurrent Subscription Strategy** - Using the concurrent subscription strategy, multiple workers of the same subscription can - connect to it simultaneously and divide the documents processing load between them to speed it up. - * Batch processing is divided between the multiple workers. - * Connection failure is handled by assigning batches of failing workers to - active available workers. - * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. -Here's an example of creating and using a data subscription: - - - -{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) -\{ - // Create the ongoing subscription task on the server - string subscriptionName = await store.Subscriptions - .CreateAsync(x => x.Company == "companies/11"); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store.Subscriptions - .GetSubscriptionWorker(subscriptionName); - - // Run the worker task and process data received from the subscription - Task workerTask = worker.Run(x => x.Items.ForEach(item => - Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), - cancellationToken); - - await workerTask; -\} -`} - - - - - - diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx deleted file mode 100644 index c2d1857b87..0000000000 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-java.mdx +++ /dev/null @@ -1,134 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`public void worker(IDocumentStore store) \{ - - // Create the ongoing subscription task on the server - SubscriptionCreationOptions options = new SubscriptionCreationOptions(); - options.setQuery("from Orders where Company = 'companies/11'"); - String subscriptionName = store.subscriptions().create(Order.class, options); - - // Create a worker on the client that will consume the subscription - SubscriptionWorker worker = store - .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); - - // Run the worker task and process data received from the subscription - worker.run(x -> \{ - for (SubscriptionBatch.Item item : x.getItems()) \{ - System.out.println("Order #" - + item.getResult().getId() - + " will be shipped via: " + item.getResult().getShipVia()); - \} - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx deleted file mode 100644 index 12e6eedbd2..0000000000 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/_what-are-data-subscriptions-nodejs.mdx +++ /dev/null @@ -1,133 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Data subscriptions provide a reliable and handy way to perform document processing on the client side. -* The server sends batches of documents to the client. - The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. - The server persists the processing progress, allowing you to pause and continue the processing. - -* In this page: - * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) - * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) - * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) - * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) - * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) - * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) - * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) - - - -## Data subscription consumption - -Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. -A worker connected to a data subscription receives a batch of documents and gets to process it. -When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. - - - -## What defines a data subscription - -Data subscriptions are defined by the server side definition and by the worker connecting to it: - -1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. - -2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. - - - -## Documents processing - -Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. -Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: - -1. If the document was changed after it was already sent. - -2. If data was received but not acknowledged. - -3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. - - -If the database has Revisions defined, the subscription can be configured to process pairs -of subsequent document revisions. -Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) - - - - -## Progress Persistence - -Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. -The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. -Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. -The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. - - -## How the worker communicates with the server - -A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: - -1. The server sends documents a batch. - -2. Worker sends acknowledgment message after it finishes processing the batch. - -3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. - - -When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. -With the Enterprise license the cluster will automatically reassign the work to another node. - - -The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. -The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. - -See the sequence diagram below that summarizes the lifetime of a subscription connection. - -![Subscription document processing](./assets/SubscriptionsDocumentProcessing.png) - - - -## Working with multiple clients - -In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. -Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. - -It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). - - - -## Data subscriptions usage example - -Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: - - - -{`async function worker() \{ - - // Create the ongoing subscription task on the server - const subscriptionName = await store.subscriptions.create(\{ - query: "from Orders where Company = 'companies/11'" - \}); - - // Create a worker on the client that will consume the subscription - const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); - - // Listen for and process data received in batches from the subscription - worker.on("batch", (batch, callback) => \{ - for (const item of batch.items) \{ - console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); - \} - - callback(); - \}); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_maintenance-operations-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_maintenance-operations-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/_subscription-with-revisioning-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/content/_subscription-with-revisioning-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx index e3d42149e8..a0eec2a405 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/maintenance-operations.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MaintenanceOperationsCsharp from './_maintenance-operations-csharp.mdx'; -import MaintenanceOperationsJava from './_maintenance-operations-java.mdx'; -import MaintenanceOperationsNodejs from './_maintenance-operations-nodejs.mdx'; +import MaintenanceOperationsCsharp from './content/_maintenance-operations-csharp.mdx'; +import MaintenanceOperationsJava from './content/_maintenance-operations-java.mdx'; +import MaintenanceOperationsNodejs from './content/_maintenance-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx index cbeeaea5c8..05ed7caa3c 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscriptionWithRevisioningCsharp from './_subscription-with-revisioning-csharp.mdx'; -import SubscriptionWithRevisioningJava from './_subscription-with-revisioning-java.mdx'; -import SubscriptionWithRevisioningNodejs from './_subscription-with-revisioning-nodejs.mdx'; +import SubscriptionWithRevisioningCsharp from './content/_subscription-with-revisioning-csharp.mdx'; +import SubscriptionWithRevisioningJava from './content/_subscription-with-revisioning-java.mdx'; +import SubscriptionWithRevisioningNodejs from './content/_subscription-with-revisioning-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/concurrent-subscriptions.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/concurrent-subscriptions.mdx index 84e853ffc4..241f4e5aee 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/concurrent-subscriptions.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/concurrent-subscriptions.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConcurrentSubscriptionsCsharp from './_concurrent-subscriptions-csharp.mdx'; -import ConcurrentSubscriptionsNodejs from './_concurrent-subscriptions-nodejs.mdx'; +import ConcurrentSubscriptionsCsharp from './content/_concurrent-subscriptions-csharp.mdx'; +import ConcurrentSubscriptionsNodejs from './content/_concurrent-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/api-overview.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/api-overview.mdx index 38766ca12a..682fd2345b 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/api-overview.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/api-overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewJava from './_api-overview-java.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewJava from './content/_api-overview-java.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_api-overview-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_api-overview-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_examples-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_examples-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/consumption/_how-to-consume-data-subscription-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/consumption/content/_how-to-consume-data-subscription-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/examples.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/examples.mdx index 71c2d3068f..49c5e9cf1d 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/examples.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/examples.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesJava from './_examples-java.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesJava from './content/_examples-java.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx index 1d7d054dcf..12a3a2ea84 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToConsumeDataSubscriptionCsharp from './_how-to-consume-data-subscription-csharp.mdx'; -import HowToConsumeDataSubscriptionJava from './_how-to-consume-data-subscription-java.mdx'; -import HowToConsumeDataSubscriptionPython from './_how-to-consume-data-subscription-python.mdx'; -import HowToConsumeDataSubscriptionNodejs from './_how-to-consume-data-subscription-nodejs.mdx'; +import HowToConsumeDataSubscriptionCsharp from './content/_how-to-consume-data-subscription-csharp.mdx'; +import HowToConsumeDataSubscriptionJava from './content/_how-to-consume-data-subscription-java.mdx'; +import HowToConsumeDataSubscriptionPython from './content/_how-to-consume-data-subscription-python.mdx'; +import HowToConsumeDataSubscriptionNodejs from './content/_how-to-consume-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/_concurrent-subscriptions-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/content/_concurrent-subscriptions-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/_concurrent-subscriptions-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/content/_concurrent-subscriptions-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx new file mode 100644 index 0000000000..30fd3f7254 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-csharp.mdx @@ -0,0 +1,160 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + +## Data subscription consumption + +* Data subscriptions are consumed by clients, called **Subscription Workers**. +* You can determine whether workers would be able to connect a subscription + [concurrently, or only one at a time](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay). +* A worker that connects to a data subscription receives a batch of documents, and gets to process it. + Depending on the code that the client provided the worker with, processing can take from seconds to hours. + When all documents are processed, the worker informs the server of its progress and the server can send it the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server-side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be sent to the worker, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that has already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +* The processing progress is persisted on the server and therefore the subscription + task can be paused and resumed from the last point it was stopped. +* The persistence mechanism also ensures that no documents are missed even in the + presence of failure, whether it's client-side related, communication, or any other disaster. +* Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. + In the case of a node failure, the processing can be automatically failed over to another node. +* The usage of **Change Vectors** allows us to continue from a point that is close to + the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents in a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license, the cluster will automatically reassign the work to another node. + + +* The status of the TCP connection is also used to determine the "state" of the worker process. + If the subscription and its workers implement a + [One Worker Per Subscription](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#worker-interplay) + strategy, as long as the connection is alive the server will not allow + other clients to consume the subscription. +* The TCP connection is kept alive and monitored using "heartbeat" messages. + If the connection is found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifespan of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +You can use a **Subscription Worker Strategy** to determine whether multiple +workers of the same subscription can connect to it one by one, or **concurrently**. + +* **One Worker Per Subscription Strategies** + The one-worker-per-subscription strategies allow workers of the same subscription + to connect to it **one worker at a time**, with different strategies to support various + inter-worker scenarios. + * One worker is allowed to take the place of another in the processing of a subscription. + Thanks to subscriptions persistence, the worker will be able to continue the work + starting at the point its predecessor got to. + * You can also configure a worker to wait for an existing connection to fail and take + its place, or to force an existing connection to close. + * Read more about these strategies [here](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#one-worker-per-subscription-strategies). + +* **Concurrent Subscription Strategy** + Using the concurrent subscription strategy, multiple workers of the same subscription can + connect to it simultaneously and divide the documents processing load between them to speed it up. + * Batch processing is divided between the multiple workers. + * Connection failure is handled by assigning batches of failing workers to + active available workers. + * Read more about this strategy [here](../../client-api/data-subscriptions/concurrent-subscriptions.mdx). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. +Here's an example of creating and using a data subscription: + + + +{`public async Task Worker(IDocumentStore store, CancellationToken cancellationToken) +\{ + // Create the ongoing subscription task on the server + string subscriptionName = await store.Subscriptions + .CreateAsync(x => x.Company == "companies/11"); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store.Subscriptions + .GetSubscriptionWorker(subscriptionName); + + // Run the worker task and process data received from the subscription + Task workerTask = worker.Run(x => x.Items.ForEach(item => + Console.WriteLine($"Order #\{item.Result.Id\} will be shipped via: \{item.Result.ShipVia\}")), + cancellationToken); + + await workerTask; +\} +`} + + + + + + diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx new file mode 100644 index 0000000000..aaa26a16f7 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-java.mdx @@ -0,0 +1,134 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`public void worker(IDocumentStore store) \{ + + // Create the ongoing subscription task on the server + SubscriptionCreationOptions options = new SubscriptionCreationOptions(); + options.setQuery("from Orders where Company = 'companies/11'"); + String subscriptionName = store.subscriptions().create(Order.class, options); + + // Create a worker on the client that will consume the subscription + SubscriptionWorker worker = store + .subscriptions().getSubscriptionWorker(Order.class, subscriptionName); + + // Run the worker task and process data received from the subscription + worker.run(x -> \{ + for (SubscriptionBatch.Item item : x.getItems()) \{ + System.out.println("Order #" + + item.getResult().getId() + + " will be shipped via: " + item.getResult().getShipVia()); + \} + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx new file mode 100644 index 0000000000..d82e45f68c --- /dev/null +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/content/_what-are-data-subscriptions-nodejs.mdx @@ -0,0 +1,133 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Data subscriptions provide a reliable and handy way to perform document processing on the client side. +* The server sends batches of documents to the client. + The client then processes the batch and will receive the next one only after it acknowledges the batch was processed. + The server persists the processing progress, allowing you to pause and continue the processing. + +* In this page: + * [Data subscription consumption](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscription-consumption) + * [What defines a data subscription](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#what-defines-a-data-subscription) + * [Documents processing](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#documents-processing) + * [Progress Persistence](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#progress-persistence) + * [How the worker communicates with the server](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#how-the-worker-communicates-with-the-server) + * [Working with multiple clients](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#working-with-multiple-clients) + * [Data subscriptions usage example](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx#data-subscriptions-usage-example) + + + +## Data subscription consumption + +Data subscriptions are consumed by clients, called subscription workers. In any given moment, only one worker can be connected to a data subscription. +A worker connected to a data subscription receives a batch of documents and gets to process it. +When it's done, depending on the code that the client gave the worker, it can take from seconds to hours. It informs the server about the progress, and the server is ready to send the next batch. + + + +## What defines a data subscription + +Data subscriptions are defined by the server side definition and by the worker connecting to it: + +1. [Subscription Creation Options](../../client-api/data-subscriptions/creation/api-overview.mdx#subscriptioncreationoptions): The documents that will be received, it's filtering and projection. + +2. [Subscription Worker Options](../../client-api/data-subscriptions/consumption/api-overview.mdx#subscriptionworkeroptions): Worker batch processing logic, batch size, interaction with other connections. + + + +## Documents processing + +Documents are sent in batches and progress will be registered only after the whole batch is processed and acknowledged. +Documents are always sent in Etag order which means that data that already been processed and acknowledged won't be sent twice, except for the following scenarios: + +1. If the document was changed after it was already sent. + +2. If data was received but not acknowledged. + +3. In case of subscription failover (`Enterprise feature`), when there is a chance that documents will be processed again, because it's not always possible to find the same starting point on a different machine. + + +If the database has Revisions defined, the subscription can be configured to process pairs +of subsequent document revisions. +Read more here: [revisions support](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx) + + + + +## Progress Persistence + +Processing progress is persisted and therefore it can be paused and resumed from the last point it was stopped. +The persistence mechanism also ensures that no documents are missed even in the presence of failure, whether it's client side related, communication, or any other disaster. +Subscriptions progress is stored in the cluster level, in the `Enterprise edition`. In the case of node failure, the processing can be automatically failed over to another node. +The usage of Change Vectors allows us to continue from a point that is close to the last point reached before failure rather than starting the process from scratch. + + +## How the worker communicates with the server + +A worker communicates with the data subscription using a custom protocol on top of a long-lived TCP connection. Each successful batch processing consists of these stages: + +1. The server sends documents a batch. + +2. Worker sends acknowledgment message after it finishes processing the batch. + +3. The server returns the client a notification that the acknowledgment persistence is done and it is ready to send the next batch. + + +When the responsible node handling the subscription is down, the subscription task can be manually reassigned to another node in the cluster. +With the Enterprise license the cluster will automatically reassign the work to another node. + + +The TCP connection is also used as the "state" of the worker process and as long as it's alive, the server will not allow other clients to consume the subscription. +The TCP connection is kept alive and monitored using "heartbeat" messages. If it's found nonfunctional, the current batch progress will be restarted. + +See the sequence diagram below that summarizes the lifetime of a subscription connection. + +![Subscription document processing](../assets/SubscriptionsDocumentProcessing.png) + + + +## Working with multiple clients + +In order to support various inter-worker scenarios, one worker is allowed to take the place of another in the processing of a subscription. +Thanks to subscriptions persistence, the worker will be able to continue the work from the point it's predecessor stopped. + +It's possible to configure that a worker will wait for an existing connection to fail, and take it's place, or we can configure it to force close an existing connection etc. See more in [Workers interplay](../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription.mdx#workers-interplay). + + + +## Data subscriptions usage example + +Data subscriptions are accessible by a document store. Here's an example of an ad-hoc creation and usage of data subscriptions: + + + +{`async function worker() \{ + + // Create the ongoing subscription task on the server + const subscriptionName = await store.subscriptions.create(\{ + query: "from Orders where Company = 'companies/11'" + \}); + + // Create a worker on the client that will consume the subscription + const worker = store.subscriptions.getSubscriptionWorker(subscriptionName); + + // Listen for and process data received in batches from the subscription + worker.on("batch", (batch, callback) => \{ + for (const item of batch.items) \{ + console.log(\`Order #$\{item.result.Id\} will be shipped via: $\{item.result.ShipVia\}\`); + \} + + callback(); + \}); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/api-overview.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/api-overview.mdx index b9fa05afa0..ffba1c8cee 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/api-overview.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/api-overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ApiOverviewCsharp from './_api-overview-csharp.mdx'; -import ApiOverviewPython from './_api-overview-python.mdx'; -import ApiOverviewNodejs from './_api-overview-nodejs.mdx'; +import ApiOverviewCsharp from './content/_api-overview-csharp.mdx'; +import ApiOverviewPython from './content/_api-overview-python.mdx'; +import ApiOverviewNodejs from './content/_api-overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_api-overview-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_api-overview-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_examples-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_examples-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-csharp.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-java.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-java.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-nodejs.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/data-subscriptions/creation/_how-to-create-data-subscription-python.mdx rename to versioned_docs/version-7.1/client-api/data-subscriptions/creation/content/_how-to-create-data-subscription-python.mdx diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/examples.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/examples.mdx index 1ecbd69bb6..560fd96307 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/examples.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/examples.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExamplesCsharp from './_examples-csharp.mdx'; -import ExamplesPython from './_examples-python.mdx'; -import ExamplesNodejs from './_examples-nodejs.mdx'; +import ExamplesCsharp from './content/_examples-csharp.mdx'; +import ExamplesPython from './content/_examples-python.mdx'; +import ExamplesNodejs from './content/_examples-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx index cc7a32aba3..a3c362a236 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/creation/how-to-create-data-subscription.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCreateDataSubscriptionCsharp from './_how-to-create-data-subscription-csharp.mdx'; -import HowToCreateDataSubscriptionJava from './_how-to-create-data-subscription-java.mdx'; -import HowToCreateDataSubscriptionPython from './_how-to-create-data-subscription-python.mdx'; -import HowToCreateDataSubscriptionNodejs from './_how-to-create-data-subscription-nodejs.mdx'; +import HowToCreateDataSubscriptionCsharp from './content/_how-to-create-data-subscription-csharp.mdx'; +import HowToCreateDataSubscriptionJava from './content/_how-to-create-data-subscription-java.mdx'; +import HowToCreateDataSubscriptionPython from './content/_how-to-create-data-subscription-python.mdx'; +import HowToCreateDataSubscriptionNodejs from './content/_how-to-create-data-subscription-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx b/versioned_docs/version-7.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx index 881ea78195..16791e745a 100644 --- a/versioned_docs/version-7.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx +++ b/versioned_docs/version-7.1/client-api/data-subscriptions/what-are-data-subscriptions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreDataSubscriptionsCsharp from './_what-are-data-subscriptions-csharp.mdx'; -import WhatAreDataSubscriptionsJava from './_what-are-data-subscriptions-java.mdx'; -import WhatAreDataSubscriptionsNodejs from './_what-are-data-subscriptions-nodejs.mdx'; +import WhatAreDataSubscriptionsCsharp from './content/_what-are-data-subscriptions-csharp.mdx'; +import WhatAreDataSubscriptionsJava from './content/_what-are-data-subscriptions-java.mdx'; +import WhatAreDataSubscriptionsNodejs from './content/_what-are-data-subscriptions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx b/versioned_docs/version-7.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/document-identifiers/_hilo-algorithm-csharp.mdx rename to versioned_docs/version-7.1/client-api/document-identifiers/content/_hilo-algorithm-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx b/versioned_docs/version-7.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/document-identifiers/_working-with-document-identifiers-csharp.mdx rename to versioned_docs/version-7.1/client-api/document-identifiers/content/_working-with-document-identifiers-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/document-identifiers/hilo-algorithm.mdx b/versioned_docs/version-7.1/client-api/document-identifiers/hilo-algorithm.mdx index d5e5afc6e6..45146864ef 100644 --- a/versioned_docs/version-7.1/client-api/document-identifiers/hilo-algorithm.mdx +++ b/versioned_docs/version-7.1/client-api/document-identifiers/hilo-algorithm.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HiloAlgorithmCsharp from './_hilo-algorithm-csharp.mdx'; +import HiloAlgorithmCsharp from './content/_hilo-algorithm-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/document-identifiers/working-with-document-identifiers.mdx b/versioned_docs/version-7.1/client-api/document-identifiers/working-with-document-identifiers.mdx index 1d6303eb46..794849e541 100644 --- a/versioned_docs/version-7.1/client-api/document-identifiers/working-with-document-identifiers.mdx +++ b/versioned_docs/version-7.1/client-api/document-identifiers/working-with-document-identifiers.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WorkingWithDocumentIdentifiersCsharp from './_working-with-document-identifiers-csharp.mdx'; +import WorkingWithDocumentIdentifiersCsharp from './content/_working-with-document-identifiers-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-csharp.mdx b/versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-csharp.mdx rename to versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-java.mdx b/versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-java.mdx rename to versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-java.mdx diff --git a/versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-nodejs.mdx b/versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/how-to/_handle-document-relationships-nodejs.mdx rename to versioned_docs/version-7.1/client-api/how-to/content/_handle-document-relationships-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx b/versioned_docs/version-7.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/how-to/_setup-aggressive-caching-csharp.mdx rename to versioned_docs/version-7.1/client-api/how-to/content/_setup-aggressive-caching-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/how-to/_setup-aggressive-caching-java.mdx b/versioned_docs/version-7.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/how-to/_setup-aggressive-caching-java.mdx rename to versioned_docs/version-7.1/client-api/how-to/content/_setup-aggressive-caching-java.mdx diff --git a/versioned_docs/version-7.1/client-api/how-to/handle-document-relationships.mdx b/versioned_docs/version-7.1/client-api/how-to/handle-document-relationships.mdx index b05dea00d3..127b092559 100644 --- a/versioned_docs/version-7.1/client-api/how-to/handle-document-relationships.mdx +++ b/versioned_docs/version-7.1/client-api/how-to/handle-document-relationships.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HandleDocumentRelationshipsCsharp from './_handle-document-relationships-csharp.mdx'; -import HandleDocumentRelationshipsJava from './_handle-document-relationships-java.mdx'; -import HandleDocumentRelationshipsNodejs from './_handle-document-relationships-nodejs.mdx'; +import HandleDocumentRelationshipsCsharp from './content/_handle-document-relationships-csharp.mdx'; +import HandleDocumentRelationshipsJava from './content/_handle-document-relationships-java.mdx'; +import HandleDocumentRelationshipsNodejs from './content/_handle-document-relationships-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/how-to/setup-aggressive-caching.mdx b/versioned_docs/version-7.1/client-api/how-to/setup-aggressive-caching.mdx index 7161a48da4..42afa3971c 100644 --- a/versioned_docs/version-7.1/client-api/how-to/setup-aggressive-caching.mdx +++ b/versioned_docs/version-7.1/client-api/how-to/setup-aggressive-caching.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetupAggressiveCachingCsharp from './_setup-aggressive-caching-csharp.mdx'; -import SetupAggressiveCachingJava from './_setup-aggressive-caching-java.mdx'; +import SetupAggressiveCachingCsharp from './content/_setup-aggressive-caching-csharp.mdx'; +import SetupAggressiveCachingJava from './content/_setup-aggressive-caching-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/net-client-versions.mdx b/versioned_docs/version-7.1/client-api/net-client-versions.mdx index 39b934542b..2fe2c3a542 100644 --- a/versioned_docs/version-7.1/client-api/net-client-versions.mdx +++ b/versioned_docs/version-7.1/client-api/net-client-versions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NetClientVersionsCsharp from './_net-client-versions-csharp.mdx'; +import NetClientVersionsCsharp from './content/_net-client-versions-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-java.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-java.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_delete-attachment-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_delete-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-java.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-java.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_get-attachment-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_get-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-java.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-java.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/attachments/_put-attachment-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/attachments/content/_put-attachment-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/delete-attachment.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/delete-attachment.mdx index b1b8dc0862..b4a5d42046 100644 --- a/versioned_docs/version-7.1/client-api/operations/attachments/delete-attachment.mdx +++ b/versioned_docs/version-7.1/client-api/operations/attachments/delete-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteAttachmentCsharp from './_delete-attachment-csharp.mdx'; -import DeleteAttachmentJava from './_delete-attachment-java.mdx'; -import DeleteAttachmentNodejs from './_delete-attachment-nodejs.mdx'; +import DeleteAttachmentCsharp from './content/_delete-attachment-csharp.mdx'; +import DeleteAttachmentJava from './content/_delete-attachment-java.mdx'; +import DeleteAttachmentNodejs from './content/_delete-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/get-attachment.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/get-attachment.mdx index dfbe7f67bf..16af9d26fc 100644 --- a/versioned_docs/version-7.1/client-api/operations/attachments/get-attachment.mdx +++ b/versioned_docs/version-7.1/client-api/operations/attachments/get-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAttachmentCsharp from './_get-attachment-csharp.mdx'; -import GetAttachmentJava from './_get-attachment-java.mdx'; -import GetAttachmentNodejs from './_get-attachment-nodejs.mdx'; +import GetAttachmentCsharp from './content/_get-attachment-csharp.mdx'; +import GetAttachmentJava from './content/_get-attachment-java.mdx'; +import GetAttachmentNodejs from './content/_get-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/attachments/put-attachment.mdx b/versioned_docs/version-7.1/client-api/operations/attachments/put-attachment.mdx index 7d63f1af0f..19a6aa8702 100644 --- a/versioned_docs/version-7.1/client-api/operations/attachments/put-attachment.mdx +++ b/versioned_docs/version-7.1/client-api/operations/attachments/put-attachment.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutAttachmentCsharp from './_put-attachment-csharp.mdx'; -import PutAttachmentJava from './_put-attachment-java.mdx'; -import PutAttachmentNodejs from './_put-attachment-nodejs.mdx'; +import PutAttachmentCsharp from './content/_put-attachment-csharp.mdx'; +import PutAttachmentJava from './content/_put-attachment-java.mdx'; +import PutAttachmentNodejs from './content/_put-attachment-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-java.mdx b/versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-java.mdx rename to versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-php.mdx b/versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-php.mdx rename to versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-python.mdx b/versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/common/_delete-by-query-python.mdx rename to versioned_docs/version-7.1/client-api/operations/common/content/_delete-by-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/common/delete-by-query.mdx b/versioned_docs/version-7.1/client-api/operations/common/delete-by-query.mdx index 9f272ec078..760f5dde72 100644 --- a/versioned_docs/version-7.1/client-api/operations/common/delete-by-query.mdx +++ b/versioned_docs/version-7.1/client-api/operations/common/delete-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteByQueryCsharp from './_delete-by-query-csharp.mdx'; -import DeleteByQueryJava from './_delete-by-query-java.mdx'; -import DeleteByQueryPython from './_delete-by-query-python.mdx'; -import DeleteByQueryPhp from './_delete-by-query-php.mdx'; -import DeleteByQueryNodejs from './_delete-by-query-nodejs.mdx'; +import DeleteByQueryCsharp from './content/_delete-by-query-csharp.mdx'; +import DeleteByQueryJava from './content/_delete-by-query-java.mdx'; +import DeleteByQueryPython from './content/_delete-by-query-python.mdx'; +import DeleteByQueryPhp from './content/_delete-by-query-php.mdx'; +import DeleteByQueryNodejs from './content/_delete-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/_what-are-operations-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/_what-are-operations-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/_what-are-operations-java.mdx b/versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/_what-are-operations-java.mdx rename to versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/_what-are-operations-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/_what-are-operations-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/_what-are-operations-php.mdx b/versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/_what-are-operations-php.mdx rename to versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/_what-are-operations-python.mdx b/versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/_what-are-operations-python.mdx rename to versioned_docs/version-7.1/client-api/operations/content/_what-are-operations-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-java.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-java.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-php.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_counter-batch-php.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_counter-batch-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_get-counters-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_get-counters-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_get-counters-java.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_get-counters-java.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_get-counters-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_get-counters-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/_get-counters-php.mdx b/versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/counters/_get-counters-php.mdx rename to versioned_docs/version-7.1/client-api/operations/counters/content/_get-counters-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/counters/counter-batch.mdx b/versioned_docs/version-7.1/client-api/operations/counters/counter-batch.mdx index c8edebeefb..c76c44fdb2 100644 --- a/versioned_docs/version-7.1/client-api/operations/counters/counter-batch.mdx +++ b/versioned_docs/version-7.1/client-api/operations/counters/counter-batch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CounterBatchCsharp from './_counter-batch-csharp.mdx'; -import CounterBatchJava from './_counter-batch-java.mdx'; -import CounterBatchPhp from './_counter-batch-php.mdx'; -import CounterBatchNodejs from './_counter-batch-nodejs.mdx'; +import CounterBatchCsharp from './content/_counter-batch-csharp.mdx'; +import CounterBatchJava from './content/_counter-batch-java.mdx'; +import CounterBatchPhp from './content/_counter-batch-php.mdx'; +import CounterBatchNodejs from './content/_counter-batch-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/counters/get-counters.mdx b/versioned_docs/version-7.1/client-api/operations/counters/get-counters.mdx index 323e1837c7..8420656da2 100644 --- a/versioned_docs/version-7.1/client-api/operations/counters/get-counters.mdx +++ b/versioned_docs/version-7.1/client-api/operations/counters/get-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCountersCsharp from './_get-counters-csharp.mdx'; -import GetCountersJava from './_get-counters-java.mdx'; -import GetCountersPhp from './_get-counters-php.mdx'; -import GetCountersNodejs from './_get-counters-nodejs.mdx'; +import GetCountersCsharp from './content/_get-counters-csharp.mdx'; +import GetCountersJava from './content/_get-counters-java.mdx'; +import GetCountersPhp from './content/_get-counters-php.mdx'; +import GetCountersNodejs from './content/_get-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-java.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-php.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-database-python.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-database-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/how-to/_switch-operations-to-a-different-node-php.mdx rename to versioned_docs/version-7.1/client-api/operations/how-to/content/_switch-operations-to-a-different-node-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx index 077dc7262b..5214f7b72b 100644 --- a/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx +++ b/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-database.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentDatabaseCsharp from './_switch-operations-to-a-different-database-csharp.mdx'; -import SwitchOperationsToADifferentDatabaseJava from './_switch-operations-to-a-different-database-java.mdx'; -import SwitchOperationsToADifferentDatabasePython from './_switch-operations-to-a-different-database-python.mdx'; -import SwitchOperationsToADifferentDatabasePhp from './_switch-operations-to-a-different-database-php.mdx'; -import SwitchOperationsToADifferentDatabaseNodejs from './_switch-operations-to-a-different-database-nodejs.mdx'; +import SwitchOperationsToADifferentDatabaseCsharp from './content/_switch-operations-to-a-different-database-csharp.mdx'; +import SwitchOperationsToADifferentDatabaseJava from './content/_switch-operations-to-a-different-database-java.mdx'; +import SwitchOperationsToADifferentDatabasePython from './content/_switch-operations-to-a-different-database-python.mdx'; +import SwitchOperationsToADifferentDatabasePhp from './content/_switch-operations-to-a-different-database-php.mdx'; +import SwitchOperationsToADifferentDatabaseNodejs from './content/_switch-operations-to-a-different-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-node.mdx b/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-node.mdx index 0607a89179..14a481c71b 100644 --- a/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-node.mdx +++ b/versioned_docs/version-7.1/client-api/operations/how-to/switch-operations-to-a-different-node.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SwitchOperationsToADifferentNodeCsharp from './_switch-operations-to-a-different-node-csharp.mdx'; -import SwitchOperationsToADifferentNodePhp from './_switch-operations-to-a-different-node-php.mdx'; -import SwitchOperationsToADifferentNodeNodejs from './_switch-operations-to-a-different-node-nodejs.mdx'; +import SwitchOperationsToADifferentNodeCsharp from './content/_switch-operations-to-a-different-node-csharp.mdx'; +import SwitchOperationsToADifferentNodePhp from './content/_switch-operations-to-a-different-node-php.mdx'; +import SwitchOperationsToADifferentNodeNodejs from './content/_switch-operations-to-a-different-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_database-settings-operation-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_database-settings-operation-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_get-client-configuration-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_get-client-configuration-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/configuration/content/_put-client-configuration-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/database-settings-operation.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/database-settings-operation.mdx index 8f7a754ac8..a6e2d88a6f 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/database-settings-operation.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/database-settings-operation.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DatabaseSettingsOperationCsharp from './_database-settings-operation-csharp.mdx'; -import DatabaseSettingsOperationPhp from './_database-settings-operation-php.mdx'; -import DatabaseSettingsOperationNodejs from './_database-settings-operation-nodejs.mdx'; +import DatabaseSettingsOperationCsharp from './content/_database-settings-operation-csharp.mdx'; +import DatabaseSettingsOperationPhp from './content/_database-settings-operation-php.mdx'; +import DatabaseSettingsOperationNodejs from './content/_database-settings-operation-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx index 046b0707ba..e70e591d2e 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/get-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetClientConfigurationCsharp from './_get-client-configuration-csharp.mdx'; -import GetClientConfigurationJava from './_get-client-configuration-java.mdx'; -import GetClientConfigurationPython from './_get-client-configuration-python.mdx'; -import GetClientConfigurationPhp from './_get-client-configuration-php.mdx'; -import GetClientConfigurationNodejs from './_get-client-configuration-nodejs.mdx'; +import GetClientConfigurationCsharp from './content/_get-client-configuration-csharp.mdx'; +import GetClientConfigurationJava from './content/_get-client-configuration-java.mdx'; +import GetClientConfigurationPython from './content/_get-client-configuration-python.mdx'; +import GetClientConfigurationPhp from './content/_get-client-configuration-php.mdx'; +import GetClientConfigurationNodejs from './content/_get-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx index 152fdaf946..6ff6c5d40e 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/configuration/put-client-configuration.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientConfigurationCsharp from './_put-client-configuration-csharp.mdx'; -import PutClientConfigurationJava from './_put-client-configuration-java.mdx'; -import PutClientConfigurationPython from './_put-client-configuration-python.mdx'; -import PutClientConfigurationPhp from './_put-client-configuration-php.mdx'; -import PutClientConfigurationNodejs from './_put-client-configuration-nodejs.mdx'; +import PutClientConfigurationCsharp from './content/_put-client-configuration-csharp.mdx'; +import PutClientConfigurationJava from './content/_put-client-configuration-java.mdx'; +import PutClientConfigurationPython from './content/_put-client-configuration-python.mdx'; +import PutClientConfigurationPhp from './content/_put-client-configuration-php.mdx'; +import PutClientConfigurationNodejs from './content/_put-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx index 411e7a0097..0de1650d28 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/add-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddConnectionStringCsharp from './_add-connection-string-csharp.mdx'; +import AddConnectionStringCsharp from './content/_add-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_add-connection-string-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_add-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_get-connection-string-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_get-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/_remove-connection-string-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/content/_remove-connection-string-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx index 0c2b4eac5d..375985d7be 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/get-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetConnectionStringCsharp from './_get-connection-string-csharp.mdx'; +import GetConnectionStringCsharp from './content/_get-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx index 097f3eefc1..170c2de116 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/connection-strings/remove-connection-string.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RemoveConnectionStringCsharp from './_remove-connection-string-csharp.mdx'; +import RemoveConnectionStringCsharp from './content/_remove-connection-string-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/_get-stats-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/content/_get-stats-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/add-etl.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/add-etl.mdx index e1ee997ddf..f4df4215da 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/add-etl.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/add-etl.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddEtlCsharp from './_add-etl-csharp.mdx'; -import AddEtlJava from './_add-etl-java.mdx'; -import AddEtlNodejs from './_add-etl-nodejs.mdx'; +import AddEtlCsharp from './content/_add-etl-csharp.mdx'; +import AddEtlJava from './content/_add-etl-java.mdx'; +import AddEtlNodejs from './content/_add-etl-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_add-etl-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_add-etl-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_reset-etl-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_reset-etl-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_reset-etl-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_reset-etl-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_update-etl-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_update-etl-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/_update-etl-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/etl/_update-etl-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/etl/content/_update-etl-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/reset-etl.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/reset-etl.mdx index cda324fd61..8962f0a244 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/reset-etl.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/reset-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetEtlCsharp from './_reset-etl-csharp.mdx'; -import ResetEtlJava from './_reset-etl-java.mdx'; +import ResetEtlCsharp from './content/_reset-etl-csharp.mdx'; +import ResetEtlJava from './content/_reset-etl-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/update-etl.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/update-etl.mdx index 2913fa18bf..31df842c72 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/etl/update-etl.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/etl/update-etl.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdateEtlCsharp from './_update-etl-csharp.mdx'; -import UpdateEtlJava from './_update-etl-java.mdx'; +import UpdateEtlCsharp from './content/_update-etl-csharp.mdx'; +import UpdateEtlJava from './content/_update-etl-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/get-stats.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/get-stats.mdx index 524445bf32..c4465a0b44 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/get-stats.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/get-stats.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetStatsCsharp from './_get-stats-csharp.mdx'; -import GetStatsJava from './_get-stats-java.mdx'; -import GetStatsPython from './_get-stats-python.mdx'; -import GetStatsPhp from './_get-stats-php.mdx'; -import GetStatsNodejs from './_get-stats-nodejs.mdx'; +import GetStatsCsharp from './content/_get-stats-csharp.mdx'; +import GetStatsJava from './content/_get-stats-java.mdx'; +import GetStatsPython from './content/_get-stats-python.mdx'; +import GetStatsPhp from './content/_get-stats-php.mdx'; +import GetStatsNodejs from './content/_get-stats-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_get-identities-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_get-identities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_increment-next-identity-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_increment-next-identity-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/identities/_seed-identity-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/identities/content/_seed-identity-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/get-identities.mdx index c7bbd9c2d5..0088f23bbf 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/get-identities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIdentitiesCsharp from './_get-identities-csharp.mdx'; -import GetIdentitiesJava from './_get-identities-java.mdx'; -import GetIdentitiesPython from './_get-identities-python.mdx'; -import GetIdentitiesPhp from './_get-identities-php.mdx'; -import GetIdentitiesNodejs from './_get-identities-nodejs.mdx'; +import GetIdentitiesCsharp from './content/_get-identities-csharp.mdx'; +import GetIdentitiesJava from './content/_get-identities-java.mdx'; +import GetIdentitiesPython from './content/_get-identities-python.mdx'; +import GetIdentitiesPhp from './content/_get-identities-php.mdx'; +import GetIdentitiesNodejs from './content/_get-identities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/increment-next-identity.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/increment-next-identity.mdx index 3dd43afc73..9745fb5152 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/increment-next-identity.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/increment-next-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncrementNextIdentityCsharp from './_increment-next-identity-csharp.mdx'; -import IncrementNextIdentityPython from './_increment-next-identity-python.mdx'; -import IncrementNextIdentityPhp from './_increment-next-identity-php.mdx'; -import IncrementNextIdentityNodejs from './_increment-next-identity-nodejs.mdx'; +import IncrementNextIdentityCsharp from './content/_increment-next-identity-csharp.mdx'; +import IncrementNextIdentityPython from './content/_increment-next-identity-python.mdx'; +import IncrementNextIdentityPhp from './content/_increment-next-identity-php.mdx'; +import IncrementNextIdentityNodejs from './content/_increment-next-identity-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/seed-identity.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/seed-identity.mdx index 2d8202aa68..fed13c4710 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/identities/seed-identity.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/identities/seed-identity.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SeedIdentityCsharp from './_seed-identity-csharp.mdx'; -import SeedIdentityPython from './_seed-identity-python.mdx'; -import SeedIdentityPhp from './_seed-identity-php.mdx'; -import SeedIdentityNodejs from './_seed-identity-nodejs.mdx'; +import SeedIdentityCsharp from './content/_seed-identity-csharp.mdx'; +import SeedIdentityPython from './content/_seed-identity-python.mdx'; +import SeedIdentityPhp from './content/_seed-identity-php.mdx'; +import SeedIdentityNodejs from './content/_seed-identity-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-errors-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-errors-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_delete-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_delete-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_disable-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_disable-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_enable-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_enable-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-errors-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-errors-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-names-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-names-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-indexes-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-indexes-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_get-terms-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_get-terms-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_index-has-changed-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_index-has-changed-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_put-indexes-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_put-indexes-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_reset-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_reset-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-lock-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-lock-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_set-index-priority-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_set-index-priority-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_start-indexing-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_start-indexing-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-index-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-index-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-java.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-php.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/indexes/_stop-indexing-python.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/indexes/content/_stop-indexing-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index-errors.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index-errors.mdx index 2d99de4957..94f423b1f1 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index-errors.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index-errors.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexErrorsCsharp from './_delete-index-errors-csharp.mdx'; -import DeleteIndexErrorsPython from './_delete-index-errors-python.mdx'; -import DeleteIndexErrorsPhp from './_delete-index-errors-php.mdx'; -import DeleteIndexErrorsNodejs from './_delete-index-errors-nodejs.mdx'; +import DeleteIndexErrorsCsharp from './content/_delete-index-errors-csharp.mdx'; +import DeleteIndexErrorsPython from './content/_delete-index-errors-python.mdx'; +import DeleteIndexErrorsPhp from './content/_delete-index-errors-php.mdx'; +import DeleteIndexErrorsNodejs from './content/_delete-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index.mdx index a2f6592dc1..35744d1b5a 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/delete-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteIndexCsharp from './_delete-index-csharp.mdx'; -import DeleteIndexJava from './_delete-index-java.mdx'; -import DeleteIndexPython from './_delete-index-python.mdx'; -import DeleteIndexPhp from './_delete-index-php.mdx'; -import DeleteIndexNodejs from './_delete-index-nodejs.mdx'; +import DeleteIndexCsharp from './content/_delete-index-csharp.mdx'; +import DeleteIndexJava from './content/_delete-index-java.mdx'; +import DeleteIndexPython from './content/_delete-index-python.mdx'; +import DeleteIndexPhp from './content/_delete-index-php.mdx'; +import DeleteIndexNodejs from './content/_delete-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/disable-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/disable-index.mdx index 0d0bf30a0a..b11e2172ae 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/disable-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/disable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DisableIndexCsharp from './_disable-index-csharp.mdx'; -import DisableIndexJava from './_disable-index-java.mdx'; -import DisableIndexPython from './_disable-index-python.mdx'; -import DisableIndexPhp from './_disable-index-php.mdx'; -import DisableIndexNodejs from './_disable-index-nodejs.mdx'; +import DisableIndexCsharp from './content/_disable-index-csharp.mdx'; +import DisableIndexJava from './content/_disable-index-java.mdx'; +import DisableIndexPython from './content/_disable-index-python.mdx'; +import DisableIndexPhp from './content/_disable-index-php.mdx'; +import DisableIndexNodejs from './content/_disable-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/enable-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/enable-index.mdx index d1b1ee6646..a2448dbd56 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/enable-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/enable-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableIndexCsharp from './_enable-index-csharp.mdx'; -import EnableIndexJava from './_enable-index-java.mdx'; -import EnableIndexPython from './_enable-index-python.mdx'; -import EnableIndexPhp from './_enable-index-php.mdx'; -import EnableIndexNodejs from './_enable-index-nodejs.mdx'; +import EnableIndexCsharp from './content/_enable-index-csharp.mdx'; +import EnableIndexJava from './content/_enable-index-java.mdx'; +import EnableIndexPython from './content/_enable-index-python.mdx'; +import EnableIndexPhp from './content/_enable-index-php.mdx'; +import EnableIndexNodejs from './content/_enable-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-errors.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-errors.mdx index 40ba0ed428..e57003a112 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-errors.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-errors.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexErrorsCsharp from './_get-index-errors-csharp.mdx'; -import GetIndexErrorsJava from './_get-index-errors-java.mdx'; -import GetIndexErrorsPython from './_get-index-errors-python.mdx'; -import GetIndexErrorsPhp from './_get-index-errors-php.mdx'; -import GetIndexErrorsNodejs from './_get-index-errors-nodejs.mdx'; +import GetIndexErrorsCsharp from './content/_get-index-errors-csharp.mdx'; +import GetIndexErrorsJava from './content/_get-index-errors-java.mdx'; +import GetIndexErrorsPython from './content/_get-index-errors-python.mdx'; +import GetIndexErrorsPhp from './content/_get-index-errors-php.mdx'; +import GetIndexErrorsNodejs from './content/_get-index-errors-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-names.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-names.mdx index f339b3b908..93915dc060 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-names.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index-names.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexNamesCsharp from './_get-index-names-csharp.mdx'; -import GetIndexNamesJava from './_get-index-names-java.mdx'; -import GetIndexNamesPython from './_get-index-names-python.mdx'; -import GetIndexNamesPhp from './_get-index-names-php.mdx'; -import GetIndexNamesNodejs from './_get-index-names-nodejs.mdx'; +import GetIndexNamesCsharp from './content/_get-index-names-csharp.mdx'; +import GetIndexNamesJava from './content/_get-index-names-java.mdx'; +import GetIndexNamesPython from './content/_get-index-names-python.mdx'; +import GetIndexNamesPhp from './content/_get-index-names-php.mdx'; +import GetIndexNamesNodejs from './content/_get-index-names-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index.mdx index 41f22c5223..15133a6a52 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexCsharp from './_get-index-csharp.mdx'; -import GetIndexJava from './_get-index-java.mdx'; -import GetIndexPython from './_get-index-python.mdx'; -import GetIndexPhp from './_get-index-php.mdx'; -import GetIndexNodejs from './_get-index-nodejs.mdx'; +import GetIndexCsharp from './content/_get-index-csharp.mdx'; +import GetIndexJava from './content/_get-index-java.mdx'; +import GetIndexPython from './content/_get-index-python.mdx'; +import GetIndexPhp from './content/_get-index-php.mdx'; +import GetIndexNodejs from './content/_get-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-indexes.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-indexes.mdx index 5e06869c5f..4fbdaa4383 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-indexes.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetIndexesCsharp from './_get-indexes-csharp.mdx'; -import GetIndexesJava from './_get-indexes-java.mdx'; -import GetIndexesPython from './_get-indexes-python.mdx'; -import GetIndexesPhp from './_get-indexes-php.mdx'; -import GetIndexesNodejs from './_get-indexes-nodejs.mdx'; +import GetIndexesCsharp from './content/_get-indexes-csharp.mdx'; +import GetIndexesJava from './content/_get-indexes-java.mdx'; +import GetIndexesPython from './content/_get-indexes-python.mdx'; +import GetIndexesPhp from './content/_get-indexes-php.mdx'; +import GetIndexesNodejs from './content/_get-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-terms.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-terms.mdx index 21cd5f88ee..1b4981f9f3 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-terms.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/get-terms.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTermsCsharp from './_get-terms-csharp.mdx'; -import GetTermsJava from './_get-terms-java.mdx'; -import GetTermsPython from './_get-terms-python.mdx'; -import GetTermsPhp from './_get-terms-php.mdx'; -import GetTermsNodejs from './_get-terms-nodejs.mdx'; +import GetTermsCsharp from './content/_get-terms-csharp.mdx'; +import GetTermsJava from './content/_get-terms-java.mdx'; +import GetTermsPython from './content/_get-terms-python.mdx'; +import GetTermsPhp from './content/_get-terms-php.mdx'; +import GetTermsNodejs from './content/_get-terms-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/index-has-changed.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/index-has-changed.mdx index b2e4319e9e..5a25288201 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/index-has-changed.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/index-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexHasChangedCsharp from './_index-has-changed-csharp.mdx'; -import IndexHasChangedJava from './_index-has-changed-java.mdx'; -import IndexHasChangedPython from './_index-has-changed-python.mdx'; -import IndexHasChangedPhp from './_index-has-changed-php.mdx'; -import IndexHasChangedNodejs from './_index-has-changed-nodejs.mdx'; +import IndexHasChangedCsharp from './content/_index-has-changed-csharp.mdx'; +import IndexHasChangedJava from './content/_index-has-changed-java.mdx'; +import IndexHasChangedPython from './content/_index-has-changed-python.mdx'; +import IndexHasChangedPhp from './content/_index-has-changed-php.mdx'; +import IndexHasChangedNodejs from './content/_index-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/put-indexes.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/put-indexes.mdx index 51621ea723..775789f882 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/put-indexes.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/put-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutIndexesCsharp from './_put-indexes-csharp.mdx'; -import PutIndexesJava from './_put-indexes-java.mdx'; -import PutIndexesPython from './_put-indexes-python.mdx'; -import PutIndexesPhp from './_put-indexes-php.mdx'; -import PutIndexesNodejs from './_put-indexes-nodejs.mdx'; +import PutIndexesCsharp from './content/_put-indexes-csharp.mdx'; +import PutIndexesJava from './content/_put-indexes-java.mdx'; +import PutIndexesPython from './content/_put-indexes-python.mdx'; +import PutIndexesPhp from './content/_put-indexes-php.mdx'; +import PutIndexesNodejs from './content/_put-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/reset-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/reset-index.mdx index 557ddd6da7..2fe124400e 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/reset-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/reset-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ResetIndexCsharp from './_reset-index-csharp.mdx'; -import ResetIndexJava from './_reset-index-java.mdx'; -import ResetIndexPython from './_reset-index-python.mdx'; -import ResetIndexPhp from './_reset-index-php.mdx'; -import ResetIndexNodejs from './_reset-index-nodejs.mdx'; +import ResetIndexCsharp from './content/_reset-index-csharp.mdx'; +import ResetIndexJava from './content/_reset-index-java.mdx'; +import ResetIndexPython from './content/_reset-index-python.mdx'; +import ResetIndexPhp from './content/_reset-index-php.mdx'; +import ResetIndexNodejs from './content/_reset-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-lock.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-lock.mdx index a54cca8ab1..95ff3012e3 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-lock.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-lock.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexLockCsharp from './_set-index-lock-csharp.mdx'; -import SetIndexLockJava from './_set-index-lock-java.mdx'; -import SetIndexLockPython from './_set-index-lock-python.mdx'; -import SetIndexLockPhp from './_set-index-lock-php.mdx'; -import SetIndexLockNodejs from './_set-index-lock-nodejs.mdx'; +import SetIndexLockCsharp from './content/_set-index-lock-csharp.mdx'; +import SetIndexLockJava from './content/_set-index-lock-java.mdx'; +import SetIndexLockPython from './content/_set-index-lock-python.mdx'; +import SetIndexLockPhp from './content/_set-index-lock-php.mdx'; +import SetIndexLockNodejs from './content/_set-index-lock-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-priority.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-priority.mdx index 8d495e1396..8f0622e4eb 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-priority.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/set-index-priority.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetIndexPriorityCsharp from './_set-index-priority-csharp.mdx'; -import SetIndexPriorityJava from './_set-index-priority-java.mdx'; -import SetIndexPriorityPython from './_set-index-priority-python.mdx'; -import SetIndexPriorityPhp from './_set-index-priority-php.mdx'; -import SetIndexPriorityNodejs from './_set-index-priority-nodejs.mdx'; +import SetIndexPriorityCsharp from './content/_set-index-priority-csharp.mdx'; +import SetIndexPriorityJava from './content/_set-index-priority-java.mdx'; +import SetIndexPriorityPython from './content/_set-index-priority-python.mdx'; +import SetIndexPriorityPhp from './content/_set-index-priority-php.mdx'; +import SetIndexPriorityNodejs from './content/_set-index-priority-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-index.mdx index 7f94087c5e..2ddee9c547 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexCsharp from './_start-index-csharp.mdx'; -import StartIndexJava from './_start-index-java.mdx'; -import StartIndexPython from './_start-index-python.mdx'; -import StartIndexPhp from './_start-index-php.mdx'; -import StartIndexNodejs from './_start-index-nodejs.mdx'; +import StartIndexCsharp from './content/_start-index-csharp.mdx'; +import StartIndexJava from './content/_start-index-java.mdx'; +import StartIndexPython from './content/_start-index-python.mdx'; +import StartIndexPhp from './content/_start-index-php.mdx'; +import StartIndexNodejs from './content/_start-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-indexing.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-indexing.mdx index e6b64be1f5..861bbe7032 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-indexing.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/start-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartIndexingCsharp from './_start-indexing-csharp.mdx'; -import StartIndexingJava from './_start-indexing-java.mdx'; -import StartIndexingPython from './_start-indexing-python.mdx'; -import StartIndexingPhp from './_start-indexing-php.mdx'; -import StartIndexingNodejs from './_start-indexing-nodejs.mdx'; +import StartIndexingCsharp from './content/_start-indexing-csharp.mdx'; +import StartIndexingJava from './content/_start-indexing-java.mdx'; +import StartIndexingPython from './content/_start-indexing-python.mdx'; +import StartIndexingPhp from './content/_start-indexing-php.mdx'; +import StartIndexingNodejs from './content/_start-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-index.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-index.mdx index 612ff571a1..4c675ff6fa 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-index.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexCsharp from './_stop-index-csharp.mdx'; -import StopIndexJava from './_stop-index-java.mdx'; -import StopIndexPython from './_stop-index-python.mdx'; -import StopIndexPhp from './_stop-index-php.mdx'; -import StopIndexNodejs from './_stop-index-nodejs.mdx'; +import StopIndexCsharp from './content/_stop-index-csharp.mdx'; +import StopIndexJava from './content/_stop-index-java.mdx'; +import StopIndexPython from './content/_stop-index-python.mdx'; +import StopIndexPhp from './content/_stop-index-php.mdx'; +import StopIndexNodejs from './content/_stop-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-indexing.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-indexing.mdx index 310924033c..3ef7b6ef58 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-indexing.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/indexes/stop-indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StopIndexingCsharp from './_stop-indexing-csharp.mdx'; -import StopIndexingJava from './_stop-indexing-java.mdx'; -import StopIndexingPython from './_stop-indexing-python.mdx'; -import StopIndexingPhp from './_stop-indexing-php.mdx'; -import StopIndexingNodejs from './_stop-indexing-nodejs.mdx'; +import StopIndexingCsharp from './content/_stop-indexing-csharp.mdx'; +import StopIndexingJava from './content/_stop-indexing-java.mdx'; +import StopIndexingPython from './content/_stop-indexing-python.mdx'; +import StopIndexingPhp from './content/_stop-indexing-php.mdx'; +import StopIndexingNodejs from './content/_stop-indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/_ongoing-task-operations-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/content/_ongoing-task-operations-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx index ecbdd10352..619c94b24d 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OngoingTaskOperationsCsharp from './_ongoing-task-operations-csharp.mdx'; +import OngoingTaskOperationsCsharp from './content/_ongoing-task-operations-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/sorters/_put-sorter-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/sorters/content/_put-sorter-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/maintenance/sorters/_put-sorter-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/maintenance/sorters/content/_put-sorter-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/put-sorter.mdx b/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/put-sorter.mdx index 957b702887..0b1824e774 100644 --- a/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/put-sorter.mdx +++ b/versioned_docs/version-7.1/client-api/operations/maintenance/sorters/put-sorter.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterCsharp from './_put-sorter-csharp.mdx'; -import PutSorterNodejs from './_put-sorter-nodejs.mdx'; +import PutSorterCsharp from './content/_put-sorter-csharp.mdx'; +import PutSorterNodejs from './content/_put-sorter-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_set-based-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_set-based-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_set-based-java.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_set-based-java.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_set-based-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_set-based-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_set-based-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_single-document-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_single-document-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_single-document-java.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_single-document-java.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/_single-document-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/patching/_single-document-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/patching/content/_single-document-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/patching/set-based.mdx b/versioned_docs/version-7.1/client-api/operations/patching/set-based.mdx index 2ec6722267..0f84ad7216 100644 --- a/versioned_docs/version-7.1/client-api/operations/patching/set-based.mdx +++ b/versioned_docs/version-7.1/client-api/operations/patching/set-based.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetBasedCsharp from './_set-based-csharp.mdx'; -import SetBasedJava from './_set-based-java.mdx'; -import SetBasedNodejs from './_set-based-nodejs.mdx'; +import SetBasedCsharp from './content/_set-based-csharp.mdx'; +import SetBasedJava from './content/_set-based-java.mdx'; +import SetBasedNodejs from './content/_set-based-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/patching/single-document.mdx b/versioned_docs/version-7.1/client-api/operations/patching/single-document.mdx index 305b79faa2..c477128af1 100644 --- a/versioned_docs/version-7.1/client-api/operations/patching/single-document.mdx +++ b/versioned_docs/version-7.1/client-api/operations/patching/single-document.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SingleDocumentCsharp from './_single-document-csharp.mdx'; -import SingleDocumentJava from './_single-document-java.mdx'; -import SingleDocumentNodejs from './_single-document-nodejs.mdx'; +import SingleDocumentCsharp from './content/_single-document-csharp.mdx'; +import SingleDocumentJava from './content/_single-document-java.mdx'; +import SingleDocumentNodejs from './content/_single-document-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/add-database-node.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/add-database-node.mdx index 47d8748c87..01b59d0442 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/add-database-node.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/add-database-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AddDatabaseNodeCsharp from './_add-database-node-csharp.mdx'; -import AddDatabaseNodePython from './_add-database-node-python.mdx'; -import AddDatabaseNodePhp from './_add-database-node-php.mdx'; -import AddDatabaseNodeNodejs from './_add-database-node-nodejs.mdx'; +import AddDatabaseNodeCsharp from './content/_add-database-node-csharp.mdx'; +import AddDatabaseNodePython from './content/_add-database-node-python.mdx'; +import AddDatabaseNodePhp from './content/_add-database-node-php.mdx'; +import AddDatabaseNodeNodejs from './content/_add-database-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_create-client-certificate-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_create-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_delete-certificate-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_delete-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificate-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificate-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificate-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificate-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificates-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificates-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_get-certificates-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_get-certificates-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/certificates/_put-client-certificate-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/certificates/content/_put-client-certificate-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx index b766a1a3cc..098386a9de 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/create-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateClientCertificateCsharp from './_create-client-certificate-csharp.mdx'; -import CreateClientCertificateJava from './_create-client-certificate-java.mdx'; -import CreateClientCertificateNodejs from './_create-client-certificate-nodejs.mdx'; +import CreateClientCertificateCsharp from './content/_create-client-certificate-csharp.mdx'; +import CreateClientCertificateJava from './content/_create-client-certificate-java.mdx'; +import CreateClientCertificateNodejs from './content/_create-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/delete-certificate.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/delete-certificate.mdx index 897234e35e..fde5585513 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/delete-certificate.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/delete-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCertificateCsharp from './_delete-certificate-csharp.mdx'; -import DeleteCertificateJava from './_delete-certificate-java.mdx'; -import DeleteCertificateNodejs from './_delete-certificate-nodejs.mdx'; +import DeleteCertificateCsharp from './content/_delete-certificate-csharp.mdx'; +import DeleteCertificateJava from './content/_delete-certificate-java.mdx'; +import DeleteCertificateNodejs from './content/_delete-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificate.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificate.mdx index ce5c617a09..a7616225a8 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificate.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificate.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificateCsharp from './_get-certificate-csharp.mdx'; -import GetCertificateJava from './_get-certificate-java.mdx'; +import GetCertificateCsharp from './content/_get-certificate-csharp.mdx'; +import GetCertificateJava from './content/_get-certificate-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificates.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificates.mdx index 9e62b3595e..83ba97af11 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificates.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/get-certificates.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCertificatesCsharp from './_get-certificates-csharp.mdx'; -import GetCertificatesJava from './_get-certificates-java.mdx'; +import GetCertificatesCsharp from './content/_get-certificates-csharp.mdx'; +import GetCertificatesJava from './content/_get-certificates-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx index d62598269f..f434c5e33d 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/certificates/put-client-certificate.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutClientCertificateCsharp from './_put-client-certificate-csharp.mdx'; -import PutClientCertificateJava from './_put-client-certificate-java.mdx'; -import PutClientCertificateNodejs from './_put-client-certificate-nodejs.mdx'; +import PutClientCertificateCsharp from './content/_put-client-certificate-csharp.mdx'; +import PutClientCertificateJava from './content/_put-client-certificate-java.mdx'; +import PutClientCertificateNodejs from './content/_put-client-certificate-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/compact-database.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/compact-database.mdx index 36b281a628..aad5c4f744 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/compact-database.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/compact-database.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CompactDatabaseCsharp from './_compact-database-csharp.mdx'; -import CompactDatabasePython from './_compact-database-python.mdx'; -import CompactDatabasePhp from './_compact-database-php.mdx'; -import CompactDatabaseNodejs from './_compact-database-nodejs.mdx'; +import CompactDatabaseCsharp from './content/_compact-database-csharp.mdx'; +import CompactDatabasePython from './content/_compact-database-python.mdx'; +import CompactDatabasePhp from './content/_compact-database-php.mdx'; +import CompactDatabaseNodejs from './content/_compact-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_get-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_get-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/configuration/_put-serverwide-client-configuration-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/configuration/content/_put-serverwide-client-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx index cab9da6b00..fbe790972d 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/get-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetServerwideClientConfigurationCsharp from './_get-serverwide-client-configuration-csharp.mdx'; -import GetServerwideClientConfigurationNodejs from './_get-serverwide-client-configuration-nodejs.mdx'; +import GetServerwideClientConfigurationCsharp from './content/_get-serverwide-client-configuration-csharp.mdx'; +import GetServerwideClientConfigurationNodejs from './content/_get-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx index 02b1f85ed6..01156912c1 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutServerwideClientConfigurationCsharp from './_put-serverwide-client-configuration-csharp.mdx'; -import PutServerwideClientConfigurationNodejs from './_put-serverwide-client-configuration-nodejs.mdx'; +import PutServerwideClientConfigurationCsharp from './content/_put-serverwide-client-configuration-csharp.mdx'; +import PutServerwideClientConfigurationNodejs from './content/_put-serverwide-client-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-php.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-php.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-python.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_add-database-node-python.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_add-database-node-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-php.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-php.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-python.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_compact-database-python.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_compact-database-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_create-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_create-database-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_create-database-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_create-database-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_delete-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_delete-database-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_delete-database-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_delete-database-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_delete-database-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_delete-database-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_delete-database-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_get-build-number-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_get-build-number-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-build-number-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_get-database-names-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_get-database-names-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-database-names-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_get-database-names-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-database-names-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_get-database-names-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_get-database-names-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_modify-conflict-solver-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_modify-conflict-solver-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_promote-database-node-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_promote-database-node-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_reorder-database-members-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_reorder-database-members-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-java.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-java.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_restore-backup-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_restore-backup-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-php.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-php.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-php.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-python.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-databases-state-python.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-databases-state-python.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/_toggle-dynamic-database-distribution-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/content/_toggle-dynamic-database-distribution-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/create-database.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/create-database.mdx index 06626431e0..59effdb582 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/create-database.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/create-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateDatabaseCsharp from './_create-database-csharp.mdx'; -import CreateDatabaseJava from './_create-database-java.mdx'; +import CreateDatabaseCsharp from './content/_create-database-csharp.mdx'; +import CreateDatabaseJava from './content/_create-database-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/delete-database.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/delete-database.mdx index 823a865d4c..a3c29a5cf4 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/delete-database.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/delete-database.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteDatabaseCsharp from './_delete-database-csharp.mdx'; -import DeleteDatabaseJava from './_delete-database-java.mdx'; +import DeleteDatabaseCsharp from './content/_delete-database-csharp.mdx'; +import DeleteDatabaseJava from './content/_delete-database-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/get-build-number.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/get-build-number.mdx index 3feec65ad5..65ed6f0d2b 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/get-build-number.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/get-build-number.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetBuildNumberCsharp from './_get-build-number-csharp.mdx'; +import GetBuildNumberCsharp from './content/_get-build-number-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/get-database-names.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/get-database-names.mdx index 29e61040e1..5c5ed82945 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/get-database-names.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/get-database-names.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetDatabaseNamesCsharp from './_get-database-names-csharp.mdx'; -import GetDatabaseNamesJava from './_get-database-names-java.mdx'; +import GetDatabaseNamesCsharp from './content/_get-database-names-csharp.mdx'; +import GetDatabaseNamesJava from './content/_get-database-names-java.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/logs/_get-logs-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/logs/content/_get-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/logs/_set-logs-configuration-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/logs/content/_set-logs-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx index 717fff9f05..0a89243169 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/get-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetLogsConfigurationCsharp from './_get-logs-configuration-csharp.mdx'; +import GetLogsConfigurationCsharp from './content/_get-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx index 40fd888f09..3cdddcb768 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/logs/set-logs-configuration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SetLogsConfigurationCsharp from './_set-logs-configuration-csharp.mdx'; +import SetLogsConfigurationCsharp from './content/_set-logs-configuration-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/modify-conflict-solver.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/modify-conflict-solver.mdx index c2af850cac..d63e118726 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/modify-conflict-solver.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/modify-conflict-solver.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ModifyConflictSolverCsharp from './_modify-conflict-solver-csharp.mdx'; +import ModifyConflictSolverCsharp from './content/_modify-conflict-solver-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/promote-database-node.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/promote-database-node.mdx index 9477875fec..8c7c1ec026 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/promote-database-node.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/promote-database-node.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PromoteDatabaseNodeCsharp from './_promote-database-node-csharp.mdx'; +import PromoteDatabaseNodeCsharp from './content/_promote-database-node-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/reorder-database-members.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/reorder-database-members.mdx index efa61e271d..9edbcb0ad3 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/reorder-database-members.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/reorder-database-members.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ReorderDatabaseMembersCsharp from './_reorder-database-members-csharp.mdx'; +import ReorderDatabaseMembersCsharp from './content/_reorder-database-members-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/restore-backup.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/restore-backup.mdx index 042ec8b357..d5eb5e9989 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/restore-backup.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/restore-backup.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RestoreBackupCsharp from './_restore-backup-csharp.mdx'; -import RestoreBackupJava from './_restore-backup-java.mdx'; -import RestoreBackupNodejs from './_restore-backup-nodejs.mdx'; +import RestoreBackupCsharp from './content/_restore-backup-csharp.mdx'; +import RestoreBackupJava from './content/_restore-backup-java.mdx'; +import RestoreBackupNodejs from './content/_restore-backup-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/sorters/_put-sorter-server-wide-csharp.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/operations/server-wide/sorters/_put-sorter-server-wide-nodejs.mdx rename to versioned_docs/version-7.1/client-api/operations/server-wide/sorters/content/_put-sorter-server-wide-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx index a6df661c64..6f845f1f78 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/sorters/put-sorter-server-wide.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutSorterServerWideCsharp from './_put-sorter-server-wide-csharp.mdx'; -import PutSorterServerWideNodejs from './_put-sorter-server-wide-nodejs.mdx'; +import PutSorterServerWideCsharp from './content/_put-sorter-server-wide-csharp.mdx'; +import PutSorterServerWideNodejs from './content/_put-sorter-server-wide-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-databases-state.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-databases-state.mdx index 85eb81d49e..396b48e8cb 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-databases-state.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-databases-state.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDatabasesStateCsharp from './_toggle-databases-state-csharp.mdx'; -import ToggleDatabasesStatePython from './_toggle-databases-state-python.mdx'; -import ToggleDatabasesStatePhp from './_toggle-databases-state-php.mdx'; -import ToggleDatabasesStateNodejs from './_toggle-databases-state-nodejs.mdx'; +import ToggleDatabasesStateCsharp from './content/_toggle-databases-state-csharp.mdx'; +import ToggleDatabasesStatePython from './content/_toggle-databases-state-python.mdx'; +import ToggleDatabasesStatePhp from './content/_toggle-databases-state-php.mdx'; +import ToggleDatabasesStateNodejs from './content/_toggle-databases-state-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx index a2b138d78a..37a9a8c8fa 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/toggle-dynamic-database-distribution.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ToggleDynamicDatabaseDistributionCsharp from './_toggle-dynamic-database-distribution-csharp.mdx'; +import ToggleDynamicDatabaseDistributionCsharp from './content/_toggle-dynamic-database-distribution-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/operations/what-are-operations.mdx b/versioned_docs/version-7.1/client-api/operations/what-are-operations.mdx index 5dcce032e4..9a48962bc8 100644 --- a/versioned_docs/version-7.1/client-api/operations/what-are-operations.mdx +++ b/versioned_docs/version-7.1/client-api/operations/what-are-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreOperationsCsharp from './_what-are-operations-csharp.mdx'; -import WhatAreOperationsJava from './_what-are-operations-java.mdx'; -import WhatAreOperationsPython from './_what-are-operations-python.mdx'; -import WhatAreOperationsPhp from './_what-are-operations-php.mdx'; -import WhatAreOperationsNodejs from './_what-are-operations-nodejs.mdx'; +import WhatAreOperationsCsharp from './content/_what-are-operations-csharp.mdx'; +import WhatAreOperationsJava from './content/_what-are-operations-java.mdx'; +import WhatAreOperationsPython from './content/_what-are-operations-python.mdx'; +import WhatAreOperationsPhp from './content/_what-are-operations-php.mdx'; +import WhatAreOperationsNodejs from './content/_what-are-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/security/_deserialization-security-csharp.mdx b/versioned_docs/version-7.1/client-api/security/content/_deserialization-security-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/security/_deserialization-security-csharp.mdx rename to versioned_docs/version-7.1/client-api/security/content/_deserialization-security-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/security/deserialization-security.mdx b/versioned_docs/version-7.1/client-api/security/deserialization-security.mdx index f0980dc2dc..99d3809a4b 100644 --- a/versioned_docs/version-7.1/client-api/security/deserialization-security.mdx +++ b/versioned_docs/version-7.1/client-api/security/deserialization-security.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeserializationSecurityCsharp from './_deserialization-security-csharp.mdx'; +import DeserializationSecurityCsharp from './content/_deserialization-security-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-csharp.mdx b/versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-php.mdx b/versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-php.mdx rename to versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-python.mdx b/versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/cluster-transaction/_overview-python.mdx rename to versioned_docs/version-7.1/client-api/session/cluster-transaction/content/_overview-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/cluster-transaction/overview.mdx b/versioned_docs/version-7.1/client-api/session/cluster-transaction/overview.mdx index 86a209dc0e..644a295c1a 100644 --- a/versioned_docs/version-7.1/client-api/session/cluster-transaction/overview.mdx +++ b/versioned_docs/version-7.1/client-api/session/cluster-transaction/overview.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-java.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-change-maximum-number-of-requests-per-session-python.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-change-maximum-number-of-requests-per-session-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-java.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-collection-assignment-for-entities-python.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-collection-assignment-for-entities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-java.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-customize-identity-property-lookup-for-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-customize-identity-property-lookup-for-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-java.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-java.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-caching-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-caching-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-python.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-disable-tracking-python.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-disable-tracking-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-java.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-php.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx b/versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/configuration/_how-to-enable-optimistic-concurrency-python.mdx rename to versioned_docs/version-7.1/client-api/session/configuration/content/_how-to-enable-optimistic-concurrency-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx index 2890a10cba..7cb513ac05 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-change-maximum-number-of-requests-per-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionJava from './_how-to-change-maximum-number-of-requests-per-session-java.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPython from './_how-to-change-maximum-number-of-requests-per-session-python.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './_how-to-change-maximum-number-of-requests-per-session-php.mdx'; -import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionCsharp from './content/_how-to-change-maximum-number-of-requests-per-session-csharp.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionJava from './content/_how-to-change-maximum-number-of-requests-per-session-java.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPython from './content/_how-to-change-maximum-number-of-requests-per-session-python.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionPhp from './content/_how-to-change-maximum-number-of-requests-per-session-php.mdx'; +import HowToChangeMaximumNumberOfRequestsPerSessionNodejs from './content/_how-to-change-maximum-number-of-requests-per-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx index e477fa0594..40cda37542 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-collection-assignment-for-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './_how-to-customize-collection-assignment-for-entities-csharp.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesJava from './_how-to-customize-collection-assignment-for-entities-java.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPython from './_how-to-customize-collection-assignment-for-entities-python.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesPhp from './_how-to-customize-collection-assignment-for-entities-php.mdx'; -import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesCsharp from './content/_how-to-customize-collection-assignment-for-entities-csharp.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesJava from './content/_how-to-customize-collection-assignment-for-entities-java.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPython from './content/_how-to-customize-collection-assignment-for-entities-python.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesPhp from './content/_how-to-customize-collection-assignment-for-entities-php.mdx'; +import HowToCustomizeCollectionAssignmentForEntitiesNodejs from './content/_how-to-customize-collection-assignment-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx index b89c2e890f..6386d22419 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-customize-identity-property-lookup-for-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './_how-to-customize-identity-property-lookup-for-entities-java.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './_how-to-customize-identity-property-lookup-for-entities-php.mdx'; -import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesCsharp from './content/_how-to-customize-identity-property-lookup-for-entities-csharp.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesJava from './content/_how-to-customize-identity-property-lookup-for-entities-java.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesPhp from './content/_how-to-customize-identity-property-lookup-for-entities-php.mdx'; +import HowToCustomizeIdentityPropertyLookupForEntitiesNodejs from './content/_how-to-customize-identity-property-lookup-for-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-caching.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-caching.mdx index 02e5bcf8b3..842a6ddf1a 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-caching.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-caching.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableCachingCsharp from './_how-to-disable-caching-csharp.mdx'; -import HowToDisableCachingJava from './_how-to-disable-caching-java.mdx'; -import HowToDisableCachingPhp from './_how-to-disable-caching-php.mdx'; -import HowToDisableCachingNodejs from './_how-to-disable-caching-nodejs.mdx'; +import HowToDisableCachingCsharp from './content/_how-to-disable-caching-csharp.mdx'; +import HowToDisableCachingJava from './content/_how-to-disable-caching-java.mdx'; +import HowToDisableCachingPhp from './content/_how-to-disable-caching-php.mdx'; +import HowToDisableCachingNodejs from './content/_how-to-disable-caching-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-tracking.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-tracking.mdx index 08d4de58e2..08e6ffd66c 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-tracking.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-disable-tracking.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToDisableTrackingCsharp from './_how-to-disable-tracking-csharp.mdx'; -import HowToDisableTrackingPython from './_how-to-disable-tracking-python.mdx'; -import HowToDisableTrackingPhp from './_how-to-disable-tracking-php.mdx'; -import HowToDisableTrackingNodejs from './_how-to-disable-tracking-nodejs.mdx'; +import HowToDisableTrackingCsharp from './content/_how-to-disable-tracking-csharp.mdx'; +import HowToDisableTrackingPython from './content/_how-to-disable-tracking-python.mdx'; +import HowToDisableTrackingPhp from './content/_how-to-disable-tracking-php.mdx'; +import HowToDisableTrackingNodejs from './content/_how-to-disable-tracking-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx b/versioned_docs/version-7.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx index 29486565e6..992fbf87a3 100644 --- a/versioned_docs/version-7.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx +++ b/versioned_docs/version-7.1/client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToEnableOptimisticConcurrencyCsharp from './_how-to-enable-optimistic-concurrency-csharp.mdx'; -import HowToEnableOptimisticConcurrencyJava from './_how-to-enable-optimistic-concurrency-java.mdx'; -import HowToEnableOptimisticConcurrencyPython from './_how-to-enable-optimistic-concurrency-python.mdx'; -import HowToEnableOptimisticConcurrencyPhp from './_how-to-enable-optimistic-concurrency-php.mdx'; -import HowToEnableOptimisticConcurrencyNodejs from './_how-to-enable-optimistic-concurrency-nodejs.mdx'; +import HowToEnableOptimisticConcurrencyCsharp from './content/_how-to-enable-optimistic-concurrency-csharp.mdx'; +import HowToEnableOptimisticConcurrencyJava from './content/_how-to-enable-optimistic-concurrency-java.mdx'; +import HowToEnableOptimisticConcurrencyPython from './content/_how-to-enable-optimistic-concurrency-python.mdx'; +import HowToEnableOptimisticConcurrencyPhp from './content/_how-to-enable-optimistic-concurrency-php.mdx'; +import HowToEnableOptimisticConcurrencyNodejs from './content/_how-to-enable-optimistic-concurrency-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/_deleting-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_deleting-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_deleting-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_deleting-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_deleting-entities-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_deleting-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_deleting-entities-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_deleting-entities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_deleting-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_deleting-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_deleting-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_deleting-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_deleting-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_deleting-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_deleting-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_deleting-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_deleting-entities-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_deleting-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_deleting-entities-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_deleting-entities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_loading-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_loading-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_loading-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_loading-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_loading-entities-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_loading-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_loading-entities-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_loading-entities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_loading-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_loading-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_loading-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_loading-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_loading-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_loading-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_loading-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_loading-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_loading-entities-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_loading-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_loading-entities-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_loading-entities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_opening-a-session-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_opening-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_opening-a-session-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_opening-a-session-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_opening-a-session-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_opening-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_opening-a-session-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_opening-a-session-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_opening-a-session-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_opening-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_opening-a-session-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_opening-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_opening-a-session-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_opening-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_opening-a-session-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_opening-a-session-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_opening-a-session-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_opening-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_opening-a-session-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_opening-a-session-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_saving-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_saving-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_saving-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_saving-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_saving-changes-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_saving-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_saving-changes-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_saving-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_saving-changes-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_saving-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_saving-changes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_saving-changes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_saving-changes-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_saving-changes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_saving-changes-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_saving-changes-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_saving-changes-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_saving-changes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_saving-changes-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_saving-changes-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_storing-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_storing-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_storing-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_storing-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_storing-entities-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_storing-entities-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_storing-entities-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_storing-entities-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_storing-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_storing-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_storing-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_storing-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_storing-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_storing-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_storing-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_storing-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_storing-entities-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_storing-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_storing-entities-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_storing-entities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_updating-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_updating-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_updating-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_updating-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_updating-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_updating-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_updating-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_updating-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_updating-entities-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_updating-entities-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_updating-entities-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_updating-entities-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_updating-entities-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_updating-entities-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_updating-entities-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_updating-entities-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx b/versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx b/versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-java.mdx rename to versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx b/versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-php.mdx rename to versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx b/versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/_what-is-a-session-and-how-does-it-work-python.mdx rename to versioned_docs/version-7.1/client-api/session/content/_what-is-a-session-and-how-does-it-work-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/deleting-entities.mdx b/versioned_docs/version-7.1/client-api/session/deleting-entities.mdx index de46d26328..43d884a92d 100644 --- a/versioned_docs/version-7.1/client-api/session/deleting-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/deleting-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingEntitiesCsharp from './_deleting-entities-csharp.mdx'; -import DeletingEntitiesJava from './_deleting-entities-java.mdx'; -import DeletingEntitiesPython from './_deleting-entities-python.mdx'; -import DeletingEntitiesPhp from './_deleting-entities-php.mdx'; -import DeletingEntitiesNodejs from './_deleting-entities-nodejs.mdx'; +import DeletingEntitiesCsharp from './content/_deleting-entities-csharp.mdx'; +import DeletingEntitiesJava from './content/_deleting-entities-java.mdx'; +import DeletingEntitiesPython from './content/_deleting-entities-python.mdx'; +import DeletingEntitiesPhp from './content/_deleting-entities-php.mdx'; +import DeletingEntitiesNodejs from './content/_deleting-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/check-if-attachment-exists.mdx b/versioned_docs/version-7.1/client-api/session/how-to/check-if-attachment-exists.mdx index af728d8e40..a63e54c411 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/check-if-attachment-exists.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/check-if-attachment-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfAttachmentExistsCsharp from './_check-if-attachment-exists-csharp.mdx'; -import CheckIfAttachmentExistsJava from './_check-if-attachment-exists-java.mdx'; -import CheckIfAttachmentExistsPython from './_check-if-attachment-exists-python.mdx'; -import CheckIfAttachmentExistsPhp from './_check-if-attachment-exists-php.mdx'; -import CheckIfAttachmentExistsNodejs from './_check-if-attachment-exists-nodejs.mdx'; +import CheckIfAttachmentExistsCsharp from './content/_check-if-attachment-exists-csharp.mdx'; +import CheckIfAttachmentExistsJava from './content/_check-if-attachment-exists-java.mdx'; +import CheckIfAttachmentExistsPython from './content/_check-if-attachment-exists-python.mdx'; +import CheckIfAttachmentExistsPhp from './content/_check-if-attachment-exists-php.mdx'; +import CheckIfAttachmentExistsNodejs from './content/_check-if-attachment-exists-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/check-if-document-exists.mdx b/versioned_docs/version-7.1/client-api/session/how-to/check-if-document-exists.mdx index 3d504a1441..d16785446e 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/check-if-document-exists.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/check-if-document-exists.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfDocumentExistsCsharp from './_check-if-document-exists-csharp.mdx'; -import CheckIfDocumentExistsJava from './_check-if-document-exists-java.mdx'; -import CheckIfDocumentExistsPython from './_check-if-document-exists-python.mdx'; -import CheckIfDocumentExistsPhp from './_check-if-document-exists-php.mdx'; -import CheckIfDocumentExistsNodejs from './_check-if-document-exists-nodejs.mdx'; +import CheckIfDocumentExistsCsharp from './content/_check-if-document-exists-csharp.mdx'; +import CheckIfDocumentExistsJava from './content/_check-if-document-exists-java.mdx'; +import CheckIfDocumentExistsPython from './content/_check-if-document-exists-python.mdx'; +import CheckIfDocumentExistsPhp from './content/_check-if-document-exists-php.mdx'; +import CheckIfDocumentExistsNodejs from './content/_check-if-document-exists-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/check-if-entity-has-changed.mdx b/versioned_docs/version-7.1/client-api/session/how-to/check-if-entity-has-changed.mdx index 38cd4ec0c0..3a31e21515 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/check-if-entity-has-changed.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/check-if-entity-has-changed.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfEntityHasChangedCsharp from './_check-if-entity-has-changed-csharp.mdx'; -import CheckIfEntityHasChangedJava from './_check-if-entity-has-changed-java.mdx'; -import CheckIfEntityHasChangedPython from './_check-if-entity-has-changed-python.mdx'; -import CheckIfEntityHasChangedPhp from './_check-if-entity-has-changed-php.mdx'; -import CheckIfEntityHasChangedNodejs from './_check-if-entity-has-changed-nodejs.mdx'; +import CheckIfEntityHasChangedCsharp from './content/_check-if-entity-has-changed-csharp.mdx'; +import CheckIfEntityHasChangedJava from './content/_check-if-entity-has-changed-java.mdx'; +import CheckIfEntityHasChangedPython from './content/_check-if-entity-has-changed-python.mdx'; +import CheckIfEntityHasChangedPhp from './content/_check-if-entity-has-changed-php.mdx'; +import CheckIfEntityHasChangedNodejs from './content/_check-if-entity-has-changed-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx b/versioned_docs/version-7.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx index 15611e9aa0..2dba3896a4 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/check-if-there-are-any-changes-on-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CheckIfThereAreAnyChangesOnASessionCsharp from './_check-if-there-are-any-changes-on-a-session-csharp.mdx'; -import CheckIfThereAreAnyChangesOnASessionJava from './_check-if-there-are-any-changes-on-a-session-java.mdx'; -import CheckIfThereAreAnyChangesOnASessionPython from './_check-if-there-are-any-changes-on-a-session-python.mdx'; -import CheckIfThereAreAnyChangesOnASessionPhp from './_check-if-there-are-any-changes-on-a-session-php.mdx'; -import CheckIfThereAreAnyChangesOnASessionNodejs from './_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; +import CheckIfThereAreAnyChangesOnASessionCsharp from './content/_check-if-there-are-any-changes-on-a-session-csharp.mdx'; +import CheckIfThereAreAnyChangesOnASessionJava from './content/_check-if-there-are-any-changes-on-a-session-java.mdx'; +import CheckIfThereAreAnyChangesOnASessionPython from './content/_check-if-there-are-any-changes-on-a-session-python.mdx'; +import CheckIfThereAreAnyChangesOnASessionPhp from './content/_check-if-there-are-any-changes-on-a-session-php.mdx'; +import CheckIfThereAreAnyChangesOnASessionNodejs from './content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/clear-a-session.mdx b/versioned_docs/version-7.1/client-api/session/how-to/clear-a-session.mdx index 37be2714f1..a8cb9ec1b7 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/clear-a-session.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/clear-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ClearASessionCsharp from './_clear-a-session-csharp.mdx'; -import ClearASessionJava from './_clear-a-session-java.mdx'; -import ClearASessionPython from './_clear-a-session-python.mdx'; -import ClearASessionPhp from './_clear-a-session-php.mdx'; -import ClearASessionNodejs from './_clear-a-session-nodejs.mdx'; +import ClearASessionCsharp from './content/_clear-a-session-csharp.mdx'; +import ClearASessionJava from './content/_clear-a-session-java.mdx'; +import ClearASessionPython from './content/_clear-a-session-python.mdx'; +import ClearASessionPhp from './content/_clear-a-session-php.mdx'; +import ClearASessionNodejs from './content/_clear-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-attachment-exists-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-attachment-exists-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-document-exists-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-document-exists-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-entity-has-changed-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-entity-has-changed-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_check-if-there-are-any-changes-on-a-session-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_check-if-there-are-any-changes-on-a-session-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_clear-a-session-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_clear-a-session-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_defer-operations-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_defer-operations-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_evict-entity-from-a-session-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_evict-entity-from-a-session-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-and-modify-entity-metadata-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-and-modify-entity-metadata-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-current-session-node-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-current-session-node-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-change-vector-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-change-vector-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-counters-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-counters-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-id-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-id-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-entity-last-modified-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-entity-last-modified-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-tracked-entities-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-tracked-entities-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-tracked-entities-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_get-tracked-entities-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_get-tracked-entities-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_get-tracked-entities-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_ignore-entity-changes-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_ignore-entity-changes-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_perform-operations-lazily-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_perform-operations-lazily-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-php.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-php.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-python.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_refresh-entity-python.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_refresh-entity-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-java.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-java.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/how-to/_subscribe-to-events-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/how-to/content/_subscribe-to-events-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/how-to/defer-operations.mdx b/versioned_docs/version-7.1/client-api/session/how-to/defer-operations.mdx index 9abbe899c1..025239ad46 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/defer-operations.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/defer-operations.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeferOperationsCsharp from './_defer-operations-csharp.mdx'; -import DeferOperationsJava from './_defer-operations-java.mdx'; -import DeferOperationsPython from './_defer-operations-python.mdx'; -import DeferOperationsPhp from './_defer-operations-php.mdx'; -import DeferOperationsNodejs from './_defer-operations-nodejs.mdx'; +import DeferOperationsCsharp from './content/_defer-operations-csharp.mdx'; +import DeferOperationsJava from './content/_defer-operations-java.mdx'; +import DeferOperationsPython from './content/_defer-operations-python.mdx'; +import DeferOperationsPhp from './content/_defer-operations-php.mdx'; +import DeferOperationsNodejs from './content/_defer-operations-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/evict-entity-from-a-session.mdx b/versioned_docs/version-7.1/client-api/session/how-to/evict-entity-from-a-session.mdx index 38cfde8172..fd92eb84e0 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/evict-entity-from-a-session.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/evict-entity-from-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EvictEntityFromASessionCsharp from './_evict-entity-from-a-session-csharp.mdx'; -import EvictEntityFromASessionJava from './_evict-entity-from-a-session-java.mdx'; -import EvictEntityFromASessionPython from './_evict-entity-from-a-session-python.mdx'; -import EvictEntityFromASessionPhp from './_evict-entity-from-a-session-php.mdx'; -import EvictEntityFromASessionNodejs from './_evict-entity-from-a-session-nodejs.mdx'; +import EvictEntityFromASessionCsharp from './content/_evict-entity-from-a-session-csharp.mdx'; +import EvictEntityFromASessionJava from './content/_evict-entity-from-a-session-java.mdx'; +import EvictEntityFromASessionPython from './content/_evict-entity-from-a-session-python.mdx'; +import EvictEntityFromASessionPhp from './content/_evict-entity-from-a-session-php.mdx'; +import EvictEntityFromASessionNodejs from './content/_evict-entity-from-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx index f49c07f092..01b9cfbc86 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-and-modify-entity-metadata.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetAndModifyEntityMetadataCsharp from './_get-and-modify-entity-metadata-csharp.mdx'; -import GetAndModifyEntityMetadataJava from './_get-and-modify-entity-metadata-java.mdx'; -import GetAndModifyEntityMetadataNodejs from './_get-and-modify-entity-metadata-nodejs.mdx'; +import GetAndModifyEntityMetadataCsharp from './content/_get-and-modify-entity-metadata-csharp.mdx'; +import GetAndModifyEntityMetadataJava from './content/_get-and-modify-entity-metadata-java.mdx'; +import GetAndModifyEntityMetadataNodejs from './content/_get-and-modify-entity-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-current-session-node.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-current-session-node.mdx index b6eff2efac..761b6cbed9 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-current-session-node.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-current-session-node.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCurrentSessionNodeCsharp from './_get-current-session-node-csharp.mdx'; -import GetCurrentSessionNodeJava from './_get-current-session-node-java.mdx'; -import GetCurrentSessionNodePhp from './_get-current-session-node-php.mdx'; -import GetCurrentSessionNodeNodejs from './_get-current-session-node-nodejs.mdx'; +import GetCurrentSessionNodeCsharp from './content/_get-current-session-node-csharp.mdx'; +import GetCurrentSessionNodeJava from './content/_get-current-session-node-java.mdx'; +import GetCurrentSessionNodePhp from './content/_get-current-session-node-php.mdx'; +import GetCurrentSessionNodeNodejs from './content/_get-current-session-node-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-change-vector.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-change-vector.mdx index 746644ec50..47cc667b96 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-change-vector.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-change-vector.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityChangeVectorCsharp from './_get-entity-change-vector-csharp.mdx'; -import GetEntityChangeVectorJava from './_get-entity-change-vector-java.mdx'; -import GetEntityChangeVectorPython from './_get-entity-change-vector-python.mdx'; -import GetEntityChangeVectorPhp from './_get-entity-change-vector-php.mdx'; -import GetEntityChangeVectorNodejs from './_get-entity-change-vector-nodejs.mdx'; +import GetEntityChangeVectorCsharp from './content/_get-entity-change-vector-csharp.mdx'; +import GetEntityChangeVectorJava from './content/_get-entity-change-vector-java.mdx'; +import GetEntityChangeVectorPython from './content/_get-entity-change-vector-python.mdx'; +import GetEntityChangeVectorPhp from './content/_get-entity-change-vector-php.mdx'; +import GetEntityChangeVectorNodejs from './content/_get-entity-change-vector-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-counters.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-counters.mdx index 040d19f663..48f26c80aa 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-counters.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-counters.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityCountersCsharp from './_get-entity-counters-csharp.mdx'; -import GetEntityCountersPython from './_get-entity-counters-python.mdx'; -import GetEntityCountersPhp from './_get-entity-counters-php.mdx'; -import GetEntityCountersNodejs from './_get-entity-counters-nodejs.mdx'; +import GetEntityCountersCsharp from './content/_get-entity-counters-csharp.mdx'; +import GetEntityCountersPython from './content/_get-entity-counters-python.mdx'; +import GetEntityCountersPhp from './content/_get-entity-counters-php.mdx'; +import GetEntityCountersNodejs from './content/_get-entity-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-id.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-id.mdx index ccd8e82336..9ed9f42dff 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-id.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-id.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityIdCsharp from './_get-entity-id-csharp.mdx'; -import GetEntityIdJava from './_get-entity-id-java.mdx'; -import GetEntityIdNodejs from './_get-entity-id-nodejs.mdx'; +import GetEntityIdCsharp from './content/_get-entity-id-csharp.mdx'; +import GetEntityIdJava from './content/_get-entity-id-java.mdx'; +import GetEntityIdNodejs from './content/_get-entity-id-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-last-modified.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-last-modified.mdx index 72ebec3519..8d5776cbe4 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-entity-last-modified.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-entity-last-modified.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntityLastModifiedCsharp from './_get-entity-last-modified-csharp.mdx'; -import GetEntityLastModifiedJava from './_get-entity-last-modified-java.mdx'; -import GetEntityLastModifiedPython from './_get-entity-last-modified-python.mdx'; -import GetEntityLastModifiedPhp from './_get-entity-last-modified-php.mdx'; -import GetEntityLastModifiedNodejs from './_get-entity-last-modified-nodejs.mdx'; +import GetEntityLastModifiedCsharp from './content/_get-entity-last-modified-csharp.mdx'; +import GetEntityLastModifiedJava from './content/_get-entity-last-modified-java.mdx'; +import GetEntityLastModifiedPython from './content/_get-entity-last-modified-python.mdx'; +import GetEntityLastModifiedPhp from './content/_get-entity-last-modified-php.mdx'; +import GetEntityLastModifiedNodejs from './content/_get-entity-last-modified-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/get-tracked-entities.mdx b/versioned_docs/version-7.1/client-api/session/how-to/get-tracked-entities.mdx index 798ba9c89d..f34535a65b 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/get-tracked-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/get-tracked-entities.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetTrackedEntitiesCsharp from './_get-tracked-entities-csharp.mdx'; -import GetTrackedEntitiesNodejs from './_get-tracked-entities-nodejs.mdx'; +import GetTrackedEntitiesCsharp from './content/_get-tracked-entities-csharp.mdx'; +import GetTrackedEntitiesNodejs from './content/_get-tracked-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/ignore-entity-changes.mdx b/versioned_docs/version-7.1/client-api/session/how-to/ignore-entity-changes.mdx index a8a9c4991c..14f860adf9 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/ignore-entity-changes.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/ignore-entity-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IgnoreEntityChangesCsharp from './_ignore-entity-changes-csharp.mdx'; -import IgnoreEntityChangesJava from './_ignore-entity-changes-java.mdx'; -import IgnoreEntityChangesPython from './_ignore-entity-changes-python.mdx'; -import IgnoreEntityChangesPhp from './_ignore-entity-changes-php.mdx'; -import IgnoreEntityChangesNodejs from './_ignore-entity-changes-nodejs.mdx'; +import IgnoreEntityChangesCsharp from './content/_ignore-entity-changes-csharp.mdx'; +import IgnoreEntityChangesJava from './content/_ignore-entity-changes-java.mdx'; +import IgnoreEntityChangesPython from './content/_ignore-entity-changes-python.mdx'; +import IgnoreEntityChangesPhp from './content/_ignore-entity-changes-php.mdx'; +import IgnoreEntityChangesNodejs from './content/_ignore-entity-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/perform-operations-lazily.mdx b/versioned_docs/version-7.1/client-api/session/how-to/perform-operations-lazily.mdx index 0178812a27..ee4090897e 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/perform-operations-lazily.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/perform-operations-lazily.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PerformOperationsLazilyCsharp from './_perform-operations-lazily-csharp.mdx'; -import PerformOperationsLazilyPython from './_perform-operations-lazily-python.mdx'; -import PerformOperationsLazilyPhp from './_perform-operations-lazily-php.mdx'; -import PerformOperationsLazilyNodejs from './_perform-operations-lazily-nodejs.mdx'; +import PerformOperationsLazilyCsharp from './content/_perform-operations-lazily-csharp.mdx'; +import PerformOperationsLazilyPython from './content/_perform-operations-lazily-python.mdx'; +import PerformOperationsLazilyPhp from './content/_perform-operations-lazily-php.mdx'; +import PerformOperationsLazilyNodejs from './content/_perform-operations-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/refresh-entity.mdx b/versioned_docs/version-7.1/client-api/session/how-to/refresh-entity.mdx index 9cc7fd7679..018014d883 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/refresh-entity.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/refresh-entity.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshEntityCsharp from './_refresh-entity-csharp.mdx'; -import RefreshEntityJava from './_refresh-entity-java.mdx'; -import RefreshEntityPython from './_refresh-entity-python.mdx'; -import RefreshEntityPhp from './_refresh-entity-php.mdx'; -import RefreshEntityNodejs from './_refresh-entity-nodejs.mdx'; +import RefreshEntityCsharp from './content/_refresh-entity-csharp.mdx'; +import RefreshEntityJava from './content/_refresh-entity-java.mdx'; +import RefreshEntityPython from './content/_refresh-entity-python.mdx'; +import RefreshEntityPhp from './content/_refresh-entity-php.mdx'; +import RefreshEntityNodejs from './content/_refresh-entity-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/how-to/subscribe-to-events.mdx b/versioned_docs/version-7.1/client-api/session/how-to/subscribe-to-events.mdx index 4a5fc1397d..80d8d339ea 100644 --- a/versioned_docs/version-7.1/client-api/session/how-to/subscribe-to-events.mdx +++ b/versioned_docs/version-7.1/client-api/session/how-to/subscribe-to-events.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SubscribeToEventsCsharp from './_subscribe-to-events-csharp.mdx'; -import SubscribeToEventsJava from './_subscribe-to-events-java.mdx'; -import SubscribeToEventsNodejs from './_subscribe-to-events-nodejs.mdx'; +import SubscribeToEventsCsharp from './content/_subscribe-to-events-csharp.mdx'; +import SubscribeToEventsJava from './content/_subscribe-to-events-java.mdx'; +import SubscribeToEventsNodejs from './content/_subscribe-to-events-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/loading-entities.mdx b/versioned_docs/version-7.1/client-api/session/loading-entities.mdx index 9181cda381..c526b245e4 100644 --- a/versioned_docs/version-7.1/client-api/session/loading-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/loading-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingEntitiesCsharp from './_loading-entities-csharp.mdx'; -import LoadingEntitiesJava from './_loading-entities-java.mdx'; -import LoadingEntitiesPython from './_loading-entities-python.mdx'; -import LoadingEntitiesPhp from './_loading-entities-php.mdx'; -import LoadingEntitiesNodejs from './_loading-entities-nodejs.mdx'; +import LoadingEntitiesCsharp from './content/_loading-entities-csharp.mdx'; +import LoadingEntitiesJava from './content/_loading-entities-java.mdx'; +import LoadingEntitiesPython from './content/_loading-entities-python.mdx'; +import LoadingEntitiesPhp from './content/_loading-entities-php.mdx'; +import LoadingEntitiesNodejs from './content/_loading-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/opening-a-session.mdx b/versioned_docs/version-7.1/client-api/session/opening-a-session.mdx index f2052db9c1..0b111de3ee 100644 --- a/versioned_docs/version-7.1/client-api/session/opening-a-session.mdx +++ b/versioned_docs/version-7.1/client-api/session/opening-a-session.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OpeningASessionCsharp from './_opening-a-session-csharp.mdx'; -import OpeningASessionJava from './_opening-a-session-java.mdx'; -import OpeningASessionPython from './_opening-a-session-python.mdx'; -import OpeningASessionPhp from './_opening-a-session-php.mdx'; -import OpeningASessionNodejs from './_opening-a-session-nodejs.mdx'; +import OpeningASessionCsharp from './content/_opening-a-session-csharp.mdx'; +import OpeningASessionJava from './content/_opening-a-session-java.mdx'; +import OpeningASessionPython from './content/_opening-a-session-python.mdx'; +import OpeningASessionPhp from './content/_opening-a-session-php.mdx'; +import OpeningASessionNodejs from './content/_opening-a-session-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx deleted file mode 100644 index 4977ffe79c..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-csharp.mdx +++ /dev/null @@ -1,204 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on 'Orders' collection - .DocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on 'Orders' collection - .AsyncDocumentQuery() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists("Freight") - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -public class Orders_ByFreight : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // Define the index-fields - public decimal Freight \{ get; set; \} - public string Id \{ get; set; \} - \} - - public Orders_ByFreight() - \{ - // Define the index Map function - Map = orders => from doc in orders - select new IndexEntry - \{ - // Index a field that might be missing in SOME documents - Freight = doc.Freight, - // Index a field that exists in ALL documents in the collection - Id = doc.Id - \}; - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = session - .Advanced - // Define a DocumentQuery on the index - .DocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`// Query the index -// =============== - -List ordersWithoutFreightField = await asyncSession - .Advanced - // Define a DocumentQuery on the index - .AsyncDocumentQuery() - // Verify the index is not stale (optional) - .WaitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - .Not.WhereExists(x => x.Freight) - // Execute the query - .ToListAsync(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx deleted file mode 100644 index 9f98fcbdd0..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-nodejs.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`const ordersWithoutFreightField = await session - // Define a query on 'orders' collection - .query({ collection: "orders" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from "orders" -where true and not exists("freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'orders' collection -// ================================================ - -class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ - - constructor() \{ - super(); - - // Define the index-fields - this.map("orders", o => (\{ - // Index a field that might be missing in SOME documents - freight: o.firstName, - // Index a field that exists in ALL documents in the collection - id: o.lastName - \})); - \} -\} -`} - - - - - - -{`// Query the index -// =============== - -const employees = await session - // Define a query on the index - .query({ indexName: "Orders/ByFreight" }) - // Search for documents that do Not contain field 'freight' - .not() - .whereExists("freight") - // Execute the query - .all(); - -// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx deleted file mode 100644 index 5e09aa7b61..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-php.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. -* To find documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, -as shown below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on 'Orders' collection - ->documentQuery(Order::class) - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`// Define a static index on the 'Orders' collection -// ================================================ - -class IndexEntry -\{ - // Define the index-fields - public ?float $freight = null; - public ?string $id = null; - - public function getFreight(): float - \{ - return $this->freight; - \} - - public function setFreight(float $freight): void - \{ - $this->freight = $freight; - \} - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} -\} - -class Orders_ByFright extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - // Define the index Map function - $this->map = "orders => from doc in orders select new \{\\n" . - " freight = doc.name, \\n" . - " id = doc.id\\n" . - "\})"; - - \} - \} -`} - - - - - - -{`// Query the index -// =============== - -/** @var array $ordersWithoutFreightField */ -$ordersWithoutFreightField = $session - ->advanced() - // Define a DocumentQuery on the index - ->documentQuery(IndexEntry::class, Orders_ByFright::class) - // Verify the index is not stale (optional) - ->waitForNonStaleResults() - // Search for documents that do Not contain field 'Freight' - ->not() - ->whereExists("Freight") - // Execute the query - ->toList(); - -// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx deleted file mode 100644 index bb534523e7..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-non-existing-field-python.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* There are situations where new fields are added to some documents in a collection over time. - -* To find the documents that are missing the newly added fields you can either: - * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) - * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) - * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) - ----- - - -## Query the collection (dynamic query) - -To run a dynamic query over a collection and find which documents are missing a specified field, -use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) -API, as demonstrated below. - -This will either create a new auto-index or add the queried field to an existing auto-index. -Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). - -**Example** - - - - -{`orders_without_freight_field = list( - session - # Define a DocumentQuery on 'Orders' collection - .document_query(object_type=Order) - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from "Orders" -where true and not exists("Freight") -// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Query a static index - -Documents with missing fields can be searched by querying a static index. - -The index definition must contain the following document fields indexed: - -* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Indexing this field will ensure that all the documents of this collection are indexed. -* A document field that is suspected to be **missing** from some documents of the queried collection. - -**Example** - - - -{`# Define a static index on the 'Orders' collection -# ================================================ - - -class Orders_ByFreight(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, freight: int = None, Id: str = None): - self.freight = freight - self.Id = Id - - def __init__(self): - # Call super().__init__() to initialize your index class - super().__init__() - # Define the index Map function - self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" -`} - - - - - - -{`# Query the index -# =============== -fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) -orders_without_freight_field = list( - session - # Define a DocumentQuery on the index - .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) - # Verify the index is not stale (optional) - .wait_for_non_stale_results() - # Search for documents that do not contain field 'freight' - .not_().where_exists("freight") -) - -# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection -`} - - - - -{`from index "Orders/ByFreight" -where true and not exists("Freight") -// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. -`} - - - - - - -## Use Studio to Run an RQL Query - -* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). - -* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: - - -{`from "Orders" -where exists("Company") and not exists("Freight") -`} - - - -* In the `where` clause: - First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. - Then search for a field that **may be missing** from some documents of the queried collection. - - ![List Documents Without a Specified Field](./assets/non-existing-field-studio-rql.png) - - 1. **Indexes** - Click to see the Indexes menu. - 2. **Query** - Select to open the Query view. - 3. **Query editor** - Write the RQL query. - 4. **Run Query** - Click to run the query. - 5. **Index used** - The name of the auto-index created to serve this query. - You can click it to see the available Studio options for this index. - 6. **Results** - This is the list of documents that do not contain the specified 'Freight' field. - (the "Freight" Field was removed from these Northwind documents for this example.) - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx deleted file mode 100644 index 76701c04da..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-csharp.mdx +++ /dev/null @@ -1,962 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `Spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `WithinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinRadius = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical area in which to search for matching documents - // Call 'WithinRadius', pass the radius and the center points coordinates - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `RelatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. -#### Circle - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on Employees collection -List employeesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within, - // Optional: customize radius units (default is Kilometers) - units: SpatialUnits.Miles)) - .ToList(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = await asyncSession - .Query() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToListAsync(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on Companies collection -List companiesWithinShape = session.Advanced - .DocumentQuery() - // Call 'Spatial' method - .Spatial( - // Call 'Point' - // Pass the path to the document fields containing the spatial data - factory => factory.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude), - // Set the geographical search criteria, call 'RelatesToShape' - criteria => criteria.RelatesToShape( - // Specify the WKT string - shapeWkt: @"POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))", - // Specify the relation between the WKT shape and the documents spatial data - relation: SpatialRelation.Within)) - .ToList(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = await asyncSession - .Query() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -List employeesSortedByDistance = session.Advanced - .DocumentQuery() - // Provide the query criteria: - .Spatial( - pointField => pointField.Point( - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = await asyncSession - .Query() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToListAsync(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -List employeesSortedByDistanceDesc = session.Advanced - .DocumentQuery() - // Call 'OrderByDistanceDescending' - .OrderByDistanceDescending( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude - ), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .ToList(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = await asyncSession - .Query() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .ThenBy(x => x.LastName) - .ToListAsync(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -List employeesSortedByRoundedDistance = session.Advanced - .DocumentQuery() - // Call 'OrderByDistance' - .OrderByDistance( - factory => factory.Point( - // Pass the path to the document fields containing the spatial data - x => x.Address.Location.Latitude, - x => x.Address.Location.Longitude) - // Round up distance to 100 km - .RoundTo(100), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .OrderBy(x => x.LastName) - .ToList(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; - -var distance = spatialResults["Distance"]; // The distance of the entity from the queried location -var latitude = spatialResults["Latitude"]; // The entity's longitude value -var longitude = spatialResults["Longitude"]; // The entity's longitude value -`} - - - - - -## Spatial API - -#### `Spatial` - - - -{`IRavenQueryable Spatial( - Expression> path, - Func clause); - -IRavenQueryable Spatial( - string fieldName, - Func clause); - -IRavenQueryable Spatial( - Func, DynamicSpatialField> field, - Func clause); - -IRavenQueryable Spatial( - DynamicSpatialField field, - Func clause); -`} - - - -| Parameters | Type | Description | -|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | -#### `DynamicSpatialFieldFactory` - - - -{`PointField Point( - Expression> latitudePath, - Expression> longitudePath); - -WktField Wkt(Expression> wktPath); -`} - - - -| Parameters | Type | Description | -|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| -| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | -#### `SpatialCriteriaFactory` - - - -{`SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria RelatesToShape( - string shapeWkt, - SpatialRelation relation, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Intersects( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Contains( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Disjoint( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria Within( - string shapeWkt, - SpatialUnits units, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); - -SpatialCriteria WithinRadius( - double radius, - double latitude, - double longitude, - SpatialUnits? radiusUnits = null, - double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | -| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | -#### `OrderByDistance` - - - -{`// From point -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistance( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistance( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistance( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistance( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - -#### `OrderByDistanceDescending` - - - -{`// From point -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude); - -// From center of WKT shape -IOrderedQueryable OrderByDistanceDescending( - Func, DynamicSpatialField> field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - DynamicSpatialField field, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt); - -// Rounding -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - double latitude, - double longitude, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - Expression> path, - string shapeWkt, - double roundFactor); - -IOrderedQueryable OrderByDistanceDescending( - string fieldName, - string shapeWkt, - double roundFactor); -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | -| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | -| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | -| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | -| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx deleted file mode 100644 index 0394bb5a15..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-java.mdx +++ /dev/null @@ -1,272 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: - -- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) -- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) -- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) - -## Spatial - - - -{`IDocumentQuery spatial(String fieldName, Function clause); - -IDocumentQuery spatial(DynamicSpatialField field, Function clause); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in an index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | - -### DynamicSpatialField - - - -{`public PointField(String latitude, String longitude) - -public WktField(String wkt) -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | - -### SpatialCriteriaFactory - - - -{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); - -SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); - -SpatialCriteria intersects(String shapeWkt); - -SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; - -SpatialCriteria contains(String shapeWkt); - -SpatialCriteria contains(String shapeWkt, double distErrorPercent); - -SpatialCriteria disjoint(String shapeWkt); - -SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); - -SpatialCriteria within(String shapeWkt); - -SpatialCriteria within(String shapeWkt, double distErrorPercent); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); - -SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | -| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | -| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | -| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL DB - Query a Spatial Index](./assets/spatial_1.png) - - -### Example I - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321)) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -`} - - - - -### Example II - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// this equals to WithinRadius(10, 32.1234, 23.4321) -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) - ) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) -`} - - - - - - -## OrderByDistance - -To sort by distance from given point use the `orderByDistance` method. The closest results will come first. - - - -{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistance(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistance( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) -`} - - - - - - -## OrderByDistanceDescending - -To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. - - - -{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); - -IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); - -IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); -`} - - - -| Parameters | | | -| ------------- | ------------- | ----- | -| **fieldName** | String | Path to spatial field in index | -| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | -| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | - -### Example - - - - -{`// return all matching entities -// within 10 kilometers radius -// from 32.1234 latitude and 23.4321 longitude coordinates -// sort results by distance from 32.1234 latitude and 23.4321 longitude point -List results = session - .query(House.class) - .spatial( - new PointField("latitude", "longitude"), - f -> f.withinRadius(10, 32.1234, 23.4321) - ) - .orderByDistanceDescending( - new PointField("latitude", "longtude"), - 32.12324, 23.4321) - .toList(); -`} - - - - -{`from Houses -where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) -order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc -`} - - - - - - -## Remarks - - -By default, distances are measured in **kilometers**. - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx deleted file mode 100644 index f63a3d807a..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-nodejs.mdx +++ /dev/null @@ -1,514 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) - * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) - * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - - -## Search by radius - -Use the `withinRadius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinRadius = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical area in which to search for matching documents - // Call 'withinRadius', pass the radius and the center points coordinates - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relatesToShape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. - - - - __Circle__: - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Define a dynamic query on 'employees' collection -const employeesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string. Note: longitude is written FIRST - "CIRCLE(-122.3060097 47.623473 d=20)", - // Specify the relation between the WKT shape and the documents spatial data - "Within", - // Customize radius units (default is Kilometers) and error percentage (Optional) - "Miles", - 0)) - .all(); -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - - - - - - - __Polygon__: - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -// Define a dynamic query on 'companies' collection -const companiesWithinShape = await session - .query({ collection: "employees" }) - // Call 'spatial' method - .spatial( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Set the geographical search criteria, call 'relatesToShape' - criteria => criteria.relatesToShape( - // Specify the WKT string - \`POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))\`, - // Specify the relation between the WKT shape and the documents spatial data - "Within")) - .all(); -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from "companies" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - - __Polygon rules__: - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - - - -## Spatial sorting - -* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. - -* By default, distance in RavenDB measured in **kilometers**. - The distance can be rounded to a specific range. - - - - __Order by distance__: - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -const employeesSortedByDistance = await session - .query({ collection: "employees" }) - // Provide the query criteria: - .spatial( - new PointField("address.location.latitude", "address.location.longitude"), - criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) - // Call 'orderByDistance' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from "employees" -where spatial.within( - spatial.point(address.location.latitude, address.location.longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - - - - - - - __Order by distance descending__: - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -const employeesSortedByDistanceDesc = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistanceDescending( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude"), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - .all(); -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - - - - - - - __Sort results by rounded distance__: - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -const employeesSortedByRoundedDistance = await session - .query({ collection: "employees" }) - // Call 'orderByDistanceDescending' - .orderByDistance( - // Specify the document fields containing the spatial data - new PointField("address.location.latitude", "address.location.longitude") - // Round up distance to 100 km - .roundTo(100), - // Sort the results by their distance (descending) from this point: - 47.623473, -122.3060097) - // A secondary sort can be applied - .orderBy("lastName") - .all(); -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field lastName. - -from "employees" -order by spatial.distance( - spatial.point(address.location.latitude, address.location.longitude), - spatial.point(47.623473, -122.3060097), - 100 -), lastName -`} - - - - - - - - - __Get resulting distance__: - -* The distance is available in the `@spatial` metadata property within each result. - -* Note the following difference between the underlying search engines: - - * When using __Lucene__: - This metadata property is always available in the results. - - * When using __Corax__: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`// Get the distance of the results: -// ================================ - -// Call 'GetMetadataFor', pass an entity from the resulting employees list -const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); - -// The distance is available in the '@spatial' metadata property -const spatialResults = metadata["@spatial"]; - -const distance = spatialResults.Distance; // The distance of the entity from the queried location -const latitude = spatialResults.Latitude; // The entity's longitude value -const longitude = spatialResults.Longitude; // The entity's longitude value -`} - - - - - - - -## Spatial API - -#### spatial - - - - -{`spatial(fieldName, clause); -spatial(field, clause); -`} - - - -| Parameters | Type | Description | -|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | - -#### DynamicSpatialField - - - - -{`class PointField \{ - latitude; - longitude; -\} - -class WktField \{ - wkt; -\} -`} - - - -| Parameters | Type | Description | -|---------------|----------|---------------------------------------------------------| -| __latitude__ | `string` | Path to the document field that contains the latitude | -| __longitude__ | `string` | Path to the document field that contains the longitude | -| __wktPath__ | `string` | Path to the document field that contains the WKT string | - -#### SpatialCriteriaFactory - - - - -{`relatesToShape(shapeWkt, relation); -relatesToShape(shapeWkt, relation, units, distErrorPercent); -intersects(shapeWkt); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, distErrorPercent); -intersects(shapeWkt, units, distErrorPercent); -contains(shapeWkt); -contains(shapeWkt, units); -contains(shapeWkt, distErrorPercent); -contains(shapeWkt, units, distErrorPercent); -disjoint(shapeWkt); -disjoint(shapeWkt, units); -disjoint(shapeWkt, distErrorPercent); -disjoint(shapeWkt, units, distErrorPercent); -within(shapeWkt); -within(shapeWkt, units); -within(shapeWkt, distErrorPercent); -within(shapeWkt, units, distErrorPercent); -withinRadius(radius, latitude, longitude); -withinRadius(radius, latitude, longitude, radiusUnits); -withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); -`} - - - -| Parameter | Type | Description | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | -| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | -| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | -| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | - -#### orderByDistance - - - - -{`orderByDistance(field, latitude, longitude); -orderByDistance(field, shapeWkt); -orderByDistance(fieldName, latitude, longitude); -orderByDistance(fieldName, latitude, longitude, roundFactor: number); -orderByDistance(fieldName, shapeWkt); -`} - - - -#### orderByDistanceDescending - - - - -{`orderByDistanceDescending(field, latitude, longitude); -orderByDistanceDescending(field, shapeWkt); -orderByDistanceDescending(fieldName, latitude, longitude); -orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); -orderByDistanceDescending(fieldName, shapeWkt); -`} - - - -| Parameter | Type | Description | -|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | -| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | -| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | -| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | -| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx deleted file mode 100644 index 736fd7b1ba..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-make-a-spatial-query-python.mdx +++ /dev/null @@ -1,537 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. - You can use either _Dynamic spatial query_ or _Spatial index query_. - - * **Dynamic spatial query** - Make a dynamic spatial query on a collection (described below). - An auto-index will be created by the server. - - * **Spatial index query** - Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) - and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). - -* To perform a spatial search, - use the `spatial` method, which provides a wide range of spatial functionalities. - -* When making a dynamic spatial query from Studio, - results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). -* In this page: - - * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) - * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) - * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) - * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) - * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) - * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) - * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) - * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) - * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) - * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) - * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) - * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) - * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) - * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) - * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) - - -## Search by radius - -Use the `within_radius` method to search for all documents containing spatial data that is located -within the specified distance from the given center point. - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_radius = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical area in which to search for matching documents - # Call 'within_radius', pass the radius and the center points coordinates - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -`} - - - - - - -## Search by shape - -* Use the `relates_to_shape` method to search for all documents containing spatial data that is located - in the specified relation to the given shape. - -* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. -#### Circle - - - - -{`# This query will return all matching employee entities -# that are located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude). - -# Define a query on Employees collection -employees_within_shape = list( - session.query(object_type=Employee) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - # Optional: customize radius units (default is Kilometers) - units=SpatialUnits.MILES, - ), - ) -) -`} - - - - -{`// This query will return all matching employee entities -// that are located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") -) -`} - - - -#### Polygon - - - - -{`# This query will return all matching company entities -# that are located within the specified polygon. - -# Define a query on Companies collection -companies_within_shape = list( - session.query(object_type=Company) - # Call 'spatial' method - .spatial( - # Create 'PointField' - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Set the geographical search criteria, call 'relates_to_shape' - lambda criteria: criteria.relates_to_shape( - # Specify the WKT string. Note: longitude is written FIRST - shape_wkt="""POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894 - ))""", - # Specify the relation between the WKT shape and the documents spatial data - relation=SpatialRelation.WITHIN, - ), - ) -) -`} - - - - -{`// This query will return all matching company entities -// that are located within the specified polygon. - -from companies -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.wkt("POLYGON (( - -118.6527948 32.7114894, - -95.8040242 37.5929338, - -102.8344151 53.3349629, - -127.5286633 48.3485664, - -129.4620208 38.0786067, - -118.7406746 32.7853769, - -118.6527948 32.7114894))") -) -`} - - - - - - -* The polygon's coordinates must be provided in counterclockwise order. - -* The first and last coordinates must mark the same location to form a closed region. - -![WKT polygon](./assets/spatial_1.png) - - - - - -## Spatial sorting - -* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. - -* By default, distance is measured by RavenDB in **kilometers**. - The distance can be rounded to a specific range. -#### Order by distance - - - - -{`# Return all matching employee entities located within 20 kilometers radius -# from point (47.623473 latitude, -122.3060097 longitude) - -# Sort the results by their distance from a specified point, -# the closest results will be listed first. - -employees_sorted_by_distance = list( - session.query(object_type=Employee) - # Provide the query criteria: - .spatial( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), - ) - # Call 'order_by_distance' - .order_by_distance( - PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 - ) -) -`} - - - - -{`// Return all matching employee entities located within 20 kilometers radius -// from point (47.623473 latitude, -122.3060097 longitude). - -// Sort the results by their distance from a specified point, -// the closest results will be listed first. - -from Employees -where spatial.within( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.circle(20, 47.623473, -122.3060097) -) -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) -`} - - - -#### Order by distance descending - - - - -{`# Return all employee entities sorted by their distance from a specified point. -# The farthest results will be listed first. - -employees_sorted_by_distance_desc = list( - session.query(object_type=Employee) - # Call 'order_by_distance_descending' - .order_by_distance_descending( - # Pass the path to document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude"), - # Sort the results by their distance (descending) from this point: - 47.623473, - -122.3060097, - ) -) -`} - - - - -{`// Return all employee entities sorted by their distance from a specified point. -// The farthest results will be listed first. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097) -) desc -`} - - - -#### Sort results by rounded distance - - - - -{`# Return all employee entities. -# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -# A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -employees_sorted_by_rounded_distance = list( - session.query(object_type=Employee) - # Call 'order_by_distance' - .order_by_distance( - # Pass the path to the document fields containing the spatial data - PointField("Address.Location.Latitude", "Address.Location.Longitude") - # Round up distance to 100 km - .round_to(100), - # Sort the results by their distance from this point: - 47.623473, - -122.3060097, - ).order_by( - "LastName" - ) -) - -pass - -o: -gion spatial_7 -spatial( -self, -field_name_or_field: Union[str, DynamicSpatialField], -clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -.. -`} - - - - -{`// Return all employee entities. -// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. -// A secondary sort can be applied within the 100 km range, e.g. by field LastName. - -from Employees -order by spatial.distance( - spatial.point(Address.Location.Latitude, Address.Location.Longitude), - spatial.point(47.623473, -122.3060097), - 100 -), LastName -`} - - - -#### Get resulting distance - -* The distance is available in the `@spatial` metadata property within each result. -* Note the following difference between the underlying search engines: - * When using **Lucene**: - This metadata property is always available in the results. - * When using **Corax**: - In order to enhance performance, this property is not included in the results by default. - To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. - Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. - - - -{`# Get the distance of the results: -# ================================ - -# Call 'get_metadata_for', pass an entity from the resulting employees list -metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) - -# The distance is available in the '@spatial' metadata property -spatial_results = metadata["@spatial"] - -distance = spatial_results["Distance"] # The distance of the entity from the queried location -latitude = spatial_results["Latitude"] # The entity's latitude value -longitude = spatial_results["Longitude"] # The entity's longitude value -`} - - - - - -## Spatial API - -#### `spatial` - - - -{`def spatial( - self, - field_name_or_field: Union[str, DynamicSpatialField], - clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], -): ... -`} - - - -| Parameters | Type | Description | -|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | -#### `DynamicSpatialField` - - - -{`class PointField(DynamicSpatialField): - def __init__(self, latitude: str, longitude: str): ... - -class WktField(DynamicSpatialField): - def __init__(self, wkt: str): ... -`} - - - -| Parameters | Type | Description | -|---------------|-------|-----------------------------------------------------------| -| **latitude** | `str` | Path to a document point field that contains the latitude | -| **longitude** | `str` | Path to a document point field that contains the longitude | -| **wkt** | `str` | Path to a document wkt field that contains the WKT string | -#### `SpatialCriteria` - - - -{`def relates_to_shape( - self, - shape_wkt: str, - relation: SpatialRelation, - units: SpatialUnits = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def intersects( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def contains( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def disjoint( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within( - self, - shape_wkt: str, - units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... - -def within_radius( - self, - radius: float, - latitude: float, - longitude: float, - radius_units: Optional[SpatialUnits] = None, - dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, -) -> SpatialCriteria: ... -`} - - - -| Parameter | Type | Description | -|---------------|-------|--------------------| -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | -| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | -| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | -| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | -| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | -#### `order_by_distance`, `order_by_distance_wkt` - - - -{`# From point & rounding - -def order_by_distance( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - -#### `order_by_distance_descending`, `order_by_distance_descending_wkt` - - - -{`# From point & rounding - -def order_by_distance_descending( - self, - field_or_field_name: Union[str, DynamicSpatialField], - latitude: float, - longitude: float, - round_factor: Optional[float] = 0.0, -) -> DocumentQuery[_T]: ... - -# From center of WKT shape - -def order_by_distance_descending_wkt( - self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | -| **latitude** | `float` | The latitude of the point from which the distance is measured | -| **longitude** | `float` | The longitude of the point from which the distance is measured | -| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | -| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx deleted file mode 100644 index 2767086d97..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-csharp.mdx +++ /dev/null @@ -1,621 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -List products = session - .Query() - .Where(x => x.Name == "chaig") - .ToList(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for single term: -// ========================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' - .ByField(x => x.Name, "chaig")) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); -foreach (string suggestedTerm in suggestions["Name"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("Name") -{ - // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' - Terms = new[] { "chaig", "tof"} -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .ByField(x => x.Name, new[] { "chaig", "tof" })) - .Execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Companies' - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to 'chop-soy china' - Term = "chop-soy china" -}; - -var request2 = new SuggestionWithTerm("Contact.Name") -{ - // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' - Term = "maria larson" -}; - -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -Dictionary suggestions = session.Advanced - // Make a dynamic document-query on collection 'Companies' - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .AndSuggestUsing(builder => builder - .ByField(x => x.Contact.Name, "maria larson")) - .Execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = await asyncSession - // Make a dynamic query on collection 'Products' - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("Name") -{ - // Looking for terms from field 'Name' that are similar to term 'chaig' - Term = "chaig", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -Dictionary suggestions = session.Advanced - // Make a dynamic query on collection 'Products' - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.Name, "chaig") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.4f, - PageSize = 5, - Distance = StringDistanceTypes.JaroWinkler, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Overloads for requesting suggestions for term(s) in a field: -ISuggestionQuery SuggestUsing(SuggestionBase suggestion); -ISuggestionQuery SuggestUsing(Action> builder); - -// Overloads requesting suggestions for term(s) in another field in the same query: -ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); -ISuggestionQuery AndSuggestUsing(Action> builder); -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------------------------| -| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`ISuggestionOperations ByField(string fieldName, string term); -ISuggestionOperations ByField(string fieldName, string[] terms); -ISuggestionOperations ByField(Expression> path, string term); -ISuggestionOperations ByField(Expression> path, string[] terms); - -ISuggestionOperations WithDisplayName(string displayName); -ISuggestionOperations WithOptions(SuggestionOptions options); -`} - - - -| Parameter | Type | Description | -|-----------------|-------------------------------|---------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **path** | `Expression>` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | - -**Suggestions options**: - - - -{`public int PageSize \{ get; set; \} -public StringDistanceTypes? Distance \{ get; set; \} -public float? Accuracy \{ get; set; \} -public SuggestionSortMode SortMode \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------------------|-------------| -| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| -| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx deleted file mode 100644 index 6b6e6f9cc3..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-nodejs.mdx +++ /dev/null @@ -1,358 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the **Northwind sample data**, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`// This dynamic query on the 'Products' collection has NO resulting documents -const products = await session - .query(\{ collection: "Products" \}) - .whereEquals("Name", "Chai") - .all(); -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`// Query for suggested terms for single term: -// ========================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' - .byField("Name", "chaig")) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); -suggestions["Name"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in field 'Name' that are similar to 'chaig': -// chai -// chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query for suggested terms for multiple terms: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' - .byField("Name", ["chaig", "tof"])) - .execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -// chai -// chang -// tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query for suggested terms in multiple fields: -// ============================================= - -const suggestions = await session - // Make a dynamic query on collection 'Companies' - .query({ collection: "Companies" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chop-soy china' in first document field (e.g. 'Name') - .suggestUsing(x => x - .byField("Name", "chop-soy china")) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .andSuggestUsing(x => x - .byField("Contact.Name", "maria larson")) - .execute(); -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in field 'Name' that is similar to 'chop-soy china': -// chop-suey chinese - -// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': -// maria larsson -// marie bertrand -// aria cruz -// paula wilson -// maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query for suggested terms - customize options and display name: -// =============================================================== - -const suggestions = await session - // Make a dynamic query on collection 'Products' - .query({ collection: "Products" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("Name", "chaig") - // Customize suggestions options - .withOptions({ - accuracy: 0.4, - pageSize: 5, - distance: "JaroWinkler", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chai -// chang -// chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`// Requesting suggestions for term(s) in a field: -suggestUsing(action); - -// Requesting suggestions for term(s) in another field in the same query: -andSuggestUsing(action); -`} - - - -| Parameter | Type | Description | -|-------------|---------------------|---------------------------------------------------------------------------------| -| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`byField(fieldName, term); -byField(fieldName, terms); - -withDisplayName(displayName); -withOptions(options); -`} - - - -| Parameter | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index field in which to search for similar terms | -| **term** | `string` | The term for which to get suggested similar terms | -| **terms** | `string[]` | List of terms for which to get suggested similar terms | -| **displayName** | `string` | A custom name for the suggestions result (optional). | -| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | - -**Suggestions options**: - -| Option | Type | Description | -|--------------|----------|-------------| -| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| -| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| -| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| -| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-php.mdx deleted file mode 100644 index dbcb968285..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-php.mdx +++ /dev/null @@ -1,270 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for a single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - - -{`$options = new SuggestionOptions(); -$options->setAccuracy(0.4); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::jaroWinkler()); -$options->setSortMode(SuggestionSortMode::popularity()); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing(function($builder) use ($options) { - $builder->byField("FullName", "johne") - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -## Suggest terms - for multiple terms - - - - -{`private int $pageSize = 15; -private ?StringDistanceTypes $distance = null; -private float $accuracy = 0.5; -private ?SuggestionSortMode $sortMode = null; - -public function __construct() -{ - $distance = StringDistanceTypes::levenshtein(); - $sortMode = SuggestionSortMode::popularity(); - ... -} - -// getters and setters for fields listed above -`} - - - - -{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); -$suggestionWithTerm->setTerm("johne"); - -/** @var array $suggestions */ -$suggestions = $session - ->query(Employee::class, Employees_ByFullName::class) - ->suggestUsing($suggestionWithTerm) - ->execute(); -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`/** - * Usage: - * - suggestUsing(SuggestionBase $suggestion); - * - suggestUsing(Closure $suggestionBuilder); - * - * @param SuggestionBase|Closure|null $suggestionOrBuilder - * @return SuggestionDocumentQueryInterface - */ -public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|-------------------------------------------------------------| -| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | -| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | - -**Builder operations**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Parameter | Type | Description | -|-----------------|---------------------------------|------------------------------------------------------| -| **$fieldName** | `?string` | The index field in which to search for similar terms | -| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | -| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | - -**Suggestions options**: - - - -{`/** - * Usage: - * - byField("fieldName", "term"); - * - byField("fieldName", ["term1", "term2"]); - */ -function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; - -function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; -`} - - - -| Option | Type | Description | -|--------------|-------------------------|---------------------------------------------| -| **$pageSize** | `int` | Maximum number of suggested terms to return | -| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | -| **$accuracy** | `float` | Suggestion accuracy | -| **$sortMode** | `?SuggestionSortMode` | Order to return results by | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-python.mdx deleted file mode 100644 index e9e99cf398..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-python.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Given a string term, the Suggestion feature will offer **similar terms** from your data. - -* Word similarities are found using string distance algorithms. - -* Examples in this article demonstrate getting suggestions with a **dynamic-query**. - For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). -* In this page: - - * Overview: - * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) - * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) - - * Examples: - * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) - * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) - - * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) - * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) - - -## What are terms - -* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - Whether making a dynamic query which generates an auto-index or using a static index, - the data from your documents is 'broken' into **terms** that are kept in the index. - -* This tokenization process (what terms will be generated) depends on the analyzer used, - various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). - -* The terms can then be queried to retrieve matching documents that contain them. - - - -## When to use suggestions - -Querying for suggestions is useful in the following scenarios: - - * **When query has no results**: - - * When searching for documents that match some condition on a given string term, - if the term is misspelled then you will Not get any results. - You can then ask RavenDB to suggest similar terms that do exist in the index. - - * The suggested terms can then be used in a new query to retrieve matching documents, - or simply presented to the user asking what they meant to query. - - * **When looking for alternative terms**: - - * When simply searching for additional alternative terms for a term that does exist. - - - -The resulting suggested terms will Not include the term for which you search, -they will only contain the similar terms. - - - - - -## Suggest terms - for single term - -Consider this example: -Based on the Northwind sample data, the following query has no resulting documents, -as no document in the Products collection contains the term `chaig` in its `Name` field. - - - -{`# This dynamic query on the 'Products' collection has NO documents -products = list(session.query(object_type=Product).where_equals("name", "chaig")) -`} - - - -* Executing the above query will generate the auto-index `Auto/Products/ByName`. - This auto-index will contain a list of all available terms from the document field `Name`. - The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). - -* If you suspect that the term `chaig` in the query criteria is written incorrectly, - you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. - - - - -{`# Query for suggested terms for single term: -# ========================================== -suggestions = ( - session.query(object_type=Product) - .suggest_using(lambda builder: builder.by_field("name", "chaig")) - .execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("name") -suggestion_request.term = "chaig" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' -from "Products" -select suggest(Name, "chaig") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in field 'name' that are similar to 'chaig':") -for suggested_term in suggestions["name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in field 'Name' that are similar to 'chaig': -# chai -# chang -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query for suggested terms for multiple terms: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' - .by_field("name", ["chaig", "tof"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("name") -# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' -suggestion_request.terms = ["chaig", "tof"] - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' -from "Products" select suggest(Name, $p0) -{ "p0" : ["chaig", "tof"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': -# chai -# chang -# tofu -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query for suggested terms in multiple fields: -# ============================================= - -suggestions = ( - session - # Make a dynamic query on collection 'Companies' - .query(object_type=Company) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chop-soy china' in first document field (e.g. 'name') - .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') - .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to 'chop-soy china' -request1.term = "chop-soy china" - -request2 = SuggestionWithTerm("contact.name") -# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' -request2.term = ["maria larson"] - -suggestions = ( - session.query(object_type=Company) - # Call 'suggest_using' - pass the suggestion request for the first field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second field - .and_suggest_using(request2).execute() -) -`} - - - - -{`// Query for suggested terms from field 'Name' and field 'Contact.Name' -from "Companies" -select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== -# -# Suggested terms in field 'name' that is similar to 'chop-soy china': -# chop-suey chinese -# -# Suggested terms in field 'contact.name' that are similar to 'maria larson': -# maria larsson -# marie bertrand -# aria cruz -# paula wilson -# maria anders -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query for suggested terms - customize options and display name: -# =============================================================== -suggestions = ( - session - # Make a dynamic query on collection 'Products' - .query(object_type=Product) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("name", "chaig") - # Customize suggestion options - .with_options( - SuggestionOptions( - accuracy=0.4, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("name") -# Looking for terms from field 'Name' that are similar to term 'chaig' -suggestion_request.term = "chaig" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=5, - page_size=5, - distance=StringDistanceTypes.JARO_WINKLER, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query for suggestions -suggestions = ( - session.query(object_type=Product) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from "Products" -select suggest( - Name, - 'chaig', - '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chai -# chang -# chartreuse verte -`} - - - - - -## The auto-index terms in Studio - -Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: - -![Figure 1. Auto-index terms](./assets/auto-index-terms.png) - -1. **The field name** - derived from the document field that was used in the dynamic-query. - In this example the field name is `Name`. - -2. **The terms** generated from the data that the Products collection documents have in their `Name` field. - - - -## Syntax - -**Suggest using**: - - - -{`# Method for requesting suggestions for term(s) in a field: -def suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... - -# Method for requesting suggestions for term(s) in another field in the same query: -def and_suggest_using( - self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] -) -> SuggestionDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|----------------|----------------------------------------------|--------------| -| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | -| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | - -| Return type | Description | -|----------------|--------------| -| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | - - -**Builder operations**: - - - -{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... - -def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... -def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|-----------------|--------------------------------|---------------------------------------------| -| **field_name** | `str` | The index field to search for similar terms | -| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | -| **display_name** | `str` | A custom name for the suggestions result | -| **options** | `SuggestionOptions` | Non-default options to use in the operation | - -**Suggestion options**: - - - -{`DEFAULT_ACCURACY = 0.5 -DEFAULT_PAGE_SIZE = 15 -DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN -DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY - -def __init__( - self, - page_size: int = DEFAULT_PAGE_SIZE, - distance: StringDistanceTypes = DEFAULT_DISTANCE, - accuracy: float = DEFAULT_ACCURACY, - sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, -): - self.page_size = page_size - self.distance = distance - self.accuracy = accuracy - self.sort_mode = sort_mode -`} - - - -| Parameter | Type | Description | -|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| -| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | -| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | -| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | -| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-count-query-results-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-count-query-results-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-customize-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-customize-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-filter-by-field-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-field-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx new file mode 100644 index 0000000000..678b7d3d12 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-csharp.mdx @@ -0,0 +1,204 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `Not` and `WhereExists` extension methods, accessible from the [DocumentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on 'Orders' collection + .DocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on 'Orders' collection + .AsyncDocumentQuery() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists("Freight") + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +public class Orders_ByFreight : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // Define the index-fields + public decimal Freight \{ get; set; \} + public string Id \{ get; set; \} + \} + + public Orders_ByFreight() + \{ + // Define the index Map function + Map = orders => from doc in orders + select new IndexEntry + \{ + // Index a field that might be missing in SOME documents + Freight = doc.Freight, + // Index a field that exists in ALL documents in the collection + Id = doc.Id + \}; + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = session + .Advanced + // Define a DocumentQuery on the index + .DocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`// Query the index +// =============== + +List ordersWithoutFreightField = await asyncSession + .Advanced + // Define a DocumentQuery on the index + .AsyncDocumentQuery() + // Verify the index is not stale (optional) + .WaitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + .Not.WhereExists(x => x.Freight) + // Execute the query + .ToListAsync(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx new file mode 100644 index 0000000000..c899fe6df8 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-nodejs.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [query](../../../client-api/session/querying/how-to-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`const ordersWithoutFreightField = await session + // Define a query on 'orders' collection + .query({ collection: "orders" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from "orders" +where true and not exists("freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'orders' collection +// ================================================ + +class Orders_ByFreight extends AbstractJavaScriptIndexCreationTask \{ + + constructor() \{ + super(); + + // Define the index-fields + this.map("orders", o => (\{ + // Index a field that might be missing in SOME documents + freight: o.firstName, + // Index a field that exists in ALL documents in the collection + id: o.lastName + \})); + \} +\} +`} + + + + + + +{`// Query the index +// =============== + +const employees = await session + // Define a query on the index + .query({ indexName: "Orders/ByFreight" }) + // Search for documents that do Not contain field 'freight' + .not() + .whereExists("freight") + // Execute the query + .all(); + +// Results will be only the documents that do Not contain the 'freight' field in 'orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx new file mode 100644 index 0000000000..5a8f39edd5 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-php.mdx @@ -0,0 +1,190 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. +* To find documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not` and `whereExists` extension methods, accessible from the [documentQuery](../../../client-api/session/querying/document-query/what-is-document-query.mdx) API, +as shown below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on 'Orders' collection + ->documentQuery(Order::class) + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`// Define a static index on the 'Orders' collection +// ================================================ + +class IndexEntry +\{ + // Define the index-fields + public ?float $freight = null; + public ?string $id = null; + + public function getFreight(): float + \{ + return $this->freight; + \} + + public function setFreight(float $freight): void + \{ + $this->freight = $freight; + \} + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} +\} + +class Orders_ByFright extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + // Define the index Map function + $this->map = "orders => from doc in orders select new \{\\n" . + " freight = doc.name, \\n" . + " id = doc.id\\n" . + "\})"; + + \} + \} +`} + + + + + + +{`// Query the index +// =============== + +/** @var array $ordersWithoutFreightField */ +$ordersWithoutFreightField = $session + ->advanced() + // Define a DocumentQuery on the index + ->documentQuery(IndexEntry::class, Orders_ByFright::class) + // Verify the index is not stale (optional) + ->waitForNonStaleResults() + // Search for documents that do Not contain field 'Freight' + ->not() + ->whereExists("Freight") + // Execute the query + ->toList(); + +// Results will be only the documents that do Not contain the 'Freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx new file mode 100644 index 0000000000..b528e7fef4 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-filter-by-non-existing-field-python.mdx @@ -0,0 +1,157 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* There are situations where new fields are added to some documents in a collection over time. + +* To find the documents that are missing the newly added fields you can either: + * [Query the collection (dynamic query)](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-the-collection-(dynamic-query)) + * [Query a static index](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#query-a-static-index) + * [Use Studio to Run an RQL Query](../../../client-api/session/querying/how-to-filter-by-non-existing-field.mdx#use-studio-to-run-an-rql-query) + +---- + + +## Query the collection (dynamic query) + +To run a dynamic query over a collection and find which documents are missing a specified field, +use the `not_` and `where_exists` methods, accessible from the [document_query](../../../client-api/session/querying/document-query/what-is-document-query.mdx) +API, as demonstrated below. + +This will either create a new auto-index or add the queried field to an existing auto-index. +Learn more about the dynamic query flow [here](../../../client-api/session/querying/how-to-query.mdx#dynamicquery). + +**Example** + + + + +{`orders_without_freight_field = list( + session + # Define a DocumentQuery on 'Orders' collection + .document_query(object_type=Order) + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from "Orders" +where true and not exists("Freight") +// \`not\` cannot be used immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Query a static index + +Documents with missing fields can be searched by querying a static index. + +The index definition must contain the following document fields indexed: + +* A document field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Indexing this field will ensure that all the documents of this collection are indexed. +* A document field that is suspected to be **missing** from some documents of the queried collection. + +**Example** + + + +{`# Define a static index on the 'Orders' collection +# ================================================ + + +class Orders_ByFreight(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, freight: int = None, Id: str = None): + self.freight = freight + self.Id = Id + + def __init__(self): + # Call super().__init__() to initialize your index class + super().__init__() + # Define the index Map function + self.map = "from o in docs.Orders select new \{ freight = o.freight, Id = o.Id \}" +`} + + + + + + +{`# Query the index +# =============== +fields = list(session.query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry)) +orders_without_freight_field = list( + session + # Define a DocumentQuery on the index + .query_index_type(Orders_ByFreight, Orders_ByFreight.IndexEntry) + # Verify the index is not stale (optional) + .wait_for_non_stale_results() + # Search for documents that do not contain field 'freight' + .not_().where_exists("freight") +) + +# Results will be only the documents that do not contain the 'freight' field in 'Orders' collection +`} + + + + +{`from index "Orders/ByFreight" +where true and not exists("Freight") +// \`not\` cannot come immediately after \`where\`, thus we use \`where true\`. +`} + + + + + + +## Use Studio to Run an RQL Query + +* Documents can be searched by missing fields using Studio's [Query view](../../../studio/database/queries/query-view.mdx). + +* Use an [RQL](../../../client-api/session/querying/what-is-rql.mdx) expression such as: + + +{`from "Orders" +where exists("Company") and not exists("Freight") +`} + + + +* In the `where` clause: + First search for a field that **exists** in **all** documents of the queried collection, e.g. the _Id_ field. + Then search for a field that **may be missing** from some documents of the queried collection. + + ![List Documents Without a Specified Field](../assets/non-existing-field-studio-rql.png) + + 1. **Indexes** + Click to see the Indexes menu. + 2. **Query** + Select to open the Query view. + 3. **Query editor** + Write the RQL query. + 4. **Run Query** + Click to run the query. + 5. **Index used** + The name of the auto-index created to serve this query. + You can click it to see the available Studio options for this index. + 6. **Results** + This is the list of documents that do not contain the specified 'Freight' field. + (the "Freight" Field was removed from these Northwind documents for this example.) + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-get-query-statistics-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx new file mode 100644 index 0000000000..a3f3e8abc4 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx @@ -0,0 +1,962 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `Spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`Spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialFieldFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteriaFactory`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`OrderByDistance`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`OrderByDistanceDescending`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `WithinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinRadius = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical area in which to search for matching documents + // Call 'WithinRadius', pass the radius and the center points coordinates + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `RelatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. +#### Circle + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on Employees collection +List employeesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + shapeWkt: "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within, + // Optional: customize radius units (default is Kilometers) + units: SpatialUnits.Miles)) + .ToList(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = await asyncSession + .Query() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToListAsync(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on Companies collection +List companiesWithinShape = session.Advanced + .DocumentQuery() + // Call 'Spatial' method + .Spatial( + // Call 'Point' + // Pass the path to the document fields containing the spatial data + factory => factory.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude), + // Set the geographical search criteria, call 'RelatesToShape' + criteria => criteria.RelatesToShape( + // Specify the WKT string + shapeWkt: @"POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))", + // Specify the relation between the WKT shape and the documents spatial data + relation: SpatialRelation.Within)) + .ToList(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `OrderByDistance` or `OrderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = await asyncSession + .Query() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +List employeesSortedByDistance = session.Advanced + .DocumentQuery() + // Provide the query criteria: + .Spatial( + pointField => pointField.Point( + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + criteria => criteria.WithinRadius(20, 47.623473, -122.3060097)) + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = await asyncSession + .Query() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToListAsync(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +List employeesSortedByDistanceDesc = session.Advanced + .DocumentQuery() + // Call 'OrderByDistanceDescending' + .OrderByDistanceDescending( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude + ), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .ToList(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = await asyncSession + .Query() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .ThenBy(x => x.LastName) + .ToListAsync(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +List employeesSortedByRoundedDistance = session.Advanced + .DocumentQuery() + // Call 'OrderByDistance' + .OrderByDistance( + factory => factory.Point( + // Pass the path to the document fields containing the spatial data + x => x.Address.Location.Latitude, + x => x.Address.Location.Longitude) + // Round up distance to 100 km + .RoundTo(100), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .OrderBy(x => x.LastName) + .ToList(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +var metadata = session.Advanced.GetMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +var spatialResults = (IDictionary)metadata[Constants.Documents.Metadata.SpatialResult]; + +var distance = spatialResults["Distance"]; // The distance of the entity from the queried location +var latitude = spatialResults["Latitude"]; // The entity's longitude value +var longitude = spatialResults["Longitude"]; // The entity's longitude value +`} + + + + + +## Spatial API + +#### `Spatial` + + + +{`IRavenQueryable Spatial( + Expression> path, + Func clause); + +IRavenQueryable Spatial( + string fieldName, + Func clause); + +IRavenQueryable Spatial( + Func, DynamicSpatialField> field, + Func clause); + +IRavenQueryable Spatial( + DynamicSpatialField field, + Func clause); +`} + + + +| Parameters | Type | Description | +|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in an index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in an index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **clause** | `Func` | Spatial criteria that will be executed on a given spatial field | +#### `DynamicSpatialFieldFactory` + + + +{`PointField Point( + Expression> latitudePath, + Expression> longitudePath); + +WktField Wkt(Expression> wktPath); +`} + + + +| Parameters | Type | Description | +|----------------------------------------------------|-------------------------------|------------------------------------------------------------------------------| +| **latitudePath** / **longitudePath** / **wktPath** | `Expression>` | Path to the field in a document containing either longitude, latitude or WKT | +#### `SpatialCriteriaFactory` + + + +{`SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria RelatesToShape( + string shapeWkt, + SpatialRelation relation, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Intersects( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Contains( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Disjoint( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria Within( + string shapeWkt, + SpatialUnits units, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); + +SpatialCriteria WithinRadius( + double radius, + double latitude, + double longitude, + SpatialUnits? radiusUnits = null, + double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| **distErrorPercent** | `double` | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** / **latitude** / **longitude** | `double` | Used to define a radius of a circle | +| **radiusUnits** / **units** | `SpatialUnits` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | +#### `OrderByDistance` + + + +{`// From point +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistance( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistance( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistance( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistance( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + +#### `OrderByDistanceDescending` + + + +{`// From point +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude); + +// From center of WKT shape +IOrderedQueryable OrderByDistanceDescending( + Func, DynamicSpatialField> field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + DynamicSpatialField field, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt); + +// Rounding +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + double latitude, + double longitude, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + Expression> path, + string shapeWkt, + double roundFactor); + +IOrderedQueryable OrderByDistanceDescending( + string fieldName, + string shapeWkt, + double roundFactor); +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **path** | `Expression>` | Path to spatial field in index
(when querying an index) | +| **fieldName** | `string` | Path to spatial field in index
(when querying an index) | +| **field** | `Func, DynamicSpatialField>`
or
`DynamicSpatialField` | Factory or field that points to a document field
(when making a dynamic query).
Either `PointField` or `WktField`. | +| **shapeWkt** | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** / **longitude** | `double` | Used to define a point from which distance will be measured | +| **roundFactor** | `double` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx new file mode 100644 index 0000000000..1791cd883c --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-java.mdx @@ -0,0 +1,272 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +Spatial indexes can be queried using the `spatial` method which contains a full spectrum of spatial methods. The following article will cover these methods: + +- [Spatial](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial) +- [OrderByDistance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) +- [OrderByDistanceDescending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedescending) + +## Spatial + + + +{`IDocumentQuery spatial(String fieldName, Function clause); + +IDocumentQuery spatial(DynamicSpatialField field, Function clause); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in an index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **clause** | Function<SpatialCriteriaFactory, SpatialCriteria> | Spatial criteria | + +### DynamicSpatialField + + + +{`public PointField(String latitude, String longitude) + +public WktField(String wkt) +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **latitude** or **longitude** or **wkt** | String | Path to the field in a document containing either longitude, latitude or WKT | + +### SpatialCriteriaFactory + + + +{`SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation); + +SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent); + +SpatialCriteria intersects(String shapeWkt); + +SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ; + +SpatialCriteria contains(String shapeWkt); + +SpatialCriteria contains(String shapeWkt, double distErrorPercent); + +SpatialCriteria disjoint(String shapeWkt); + +SpatialCriteria disjoint(String shapeWkt, double distErrorPercent); + +SpatialCriteria within(String shapeWkt); + +SpatialCriteria within(String shapeWkt, double distErrorPercent); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits); + +SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used in operation | +| **relation** | SpatialRelation | Shape relation. Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **distErrorPercent** | double | Maximum distance error tolerance in percents. Default: 0.025 | +| **radius** or **latitude** or **longitude** | double | Used to define a radius circle | +| **radiusUnits** | SpatialUnits | Determines if circle should be calculated in `KILOMETERS` or `MILES` units | + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL DB - Query a Spatial Index](../assets/spatial_1.png) + + +### Example I + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321)) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +`} + + + + +### Example II + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// this equals to WithinRadius(10, 32.1234, 23.4321) +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN) + ) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)')) +`} + + + + + + +## OrderByDistance + +To sort by distance from given point use the `orderByDistance` method. The closest results will come first. + + + +{`IDocumentQuery orderByDistance(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistance(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistance(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistance(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistance( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) +`} + + + + + + +## OrderByDistanceDescending + +To sort by distance from given point use the `OrderByDistanceDescending` method. The farthest results will come first. + + + +{`IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(DynamicSpatialField field, String shapeWkt); + +IDocumentQuery orderByDistanceDescending(String fieldName, double latitude, double longitude); + +IDocumentQuery orderByDistanceDescending(String fieldName, String shapeWkt); +`} + + + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Path to spatial field in index | +| **field** | DynamicSpatialField | Field that points to a dynamic field (used with auto-indexes). Either `PointField` or `WktField` | +| **shapeWkt** | String | WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| **latitude** or **longitude** | double | Used to define a point from which distance will be measured | + +### Example + + + + +{`// return all matching entities +// within 10 kilometers radius +// from 32.1234 latitude and 23.4321 longitude coordinates +// sort results by distance from 32.1234 latitude and 23.4321 longitude point +List results = session + .query(House.class) + .spatial( + new PointField("latitude", "longitude"), + f -> f.withinRadius(10, 32.1234, 23.4321) + ) + .orderByDistanceDescending( + new PointField("latitude", "longtude"), + 32.12324, 23.4321) + .toList(); +`} + + + + +{`from Houses +where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321)) +order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc +`} + + + + + + +## Remarks + + +By default, distances are measured in **kilometers**. + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx new file mode 100644 index 0000000000..3229d3c59f --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx @@ -0,0 +1,514 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistance) + * [Order by distance desc](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#orderbydistancedesc) + * [Rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#roundeddistance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#getresultingdistance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + + +## Search by radius + +Use the `withinRadius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinRadius = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical area in which to search for matching documents + // Call 'withinRadius', pass the radius and the center points coordinates + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relatesToShape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a __circle__ or a __polygon__ in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `Within`, `Contains`, `Disjoint`, `Intersects`. + + + + __Circle__: + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Define a dynamic query on 'employees' collection +const employeesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string. Note: longitude is written FIRST + "CIRCLE(-122.3060097 47.623473 d=20)", + // Specify the relation between the WKT shape and the documents spatial data + "Within", + // Customize radius units (default is Kilometers) and error percentage (Optional) + "Miles", + 0)) + .all(); +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + + + + + + + __Polygon__: + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +// Define a dynamic query on 'companies' collection +const companiesWithinShape = await session + .query({ collection: "employees" }) + // Call 'spatial' method + .spatial( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Set the geographical search criteria, call 'relatesToShape' + criteria => criteria.relatesToShape( + // Specify the WKT string + \`POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))\`, + // Specify the relation between the WKT shape and the documents spatial data + "Within")) + .all(); +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from "companies" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + + __Polygon rules__: + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + + + +## Spatial sorting + +* Use `orderByDistance` or `orderByDistanceDescending` to sort the results by distance from a given point. + +* By default, distance in RavenDB measured in **kilometers**. + The distance can be rounded to a specific range. + + + + __Order by distance__: + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +const employeesSortedByDistance = await session + .query({ collection: "employees" }) + // Provide the query criteria: + .spatial( + new PointField("address.location.latitude", "address.location.longitude"), + criteria => criteria.withinRadius(20, 47.623473, -122.3060097)) + // Call 'orderByDistance' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from "employees" +where spatial.within( + spatial.point(address.location.latitude, address.location.longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + + + + + + + __Order by distance descending__: + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +const employeesSortedByDistanceDesc = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistanceDescending( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude"), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + .all(); +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + + + + + + + __Sort results by rounded distance__: + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +const employeesSortedByRoundedDistance = await session + .query({ collection: "employees" }) + // Call 'orderByDistanceDescending' + .orderByDistance( + // Specify the document fields containing the spatial data + new PointField("address.location.latitude", "address.location.longitude") + // Round up distance to 100 km + .roundTo(100), + // Sort the results by their distance (descending) from this point: + 47.623473, -122.3060097) + // A secondary sort can be applied + .orderBy("lastName") + .all(); +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field lastName. + +from "employees" +order by spatial.distance( + spatial.point(address.location.latitude, address.location.longitude), + spatial.point(47.623473, -122.3060097), + 100 +), lastName +`} + + + + + + + + + __Get resulting distance__: + +* The distance is available in the `@spatial` metadata property within each result. + +* Note the following difference between the underlying search engines: + + * When using __Lucene__: + This metadata property is always available in the results. + + * When using __Corax__: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`// Get the distance of the results: +// ================================ + +// Call 'GetMetadataFor', pass an entity from the resulting employees list +const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]); + +// The distance is available in the '@spatial' metadata property +const spatialResults = metadata["@spatial"]; + +const distance = spatialResults.Distance; // The distance of the entity from the queried location +const latitude = spatialResults.Latitude; // The entity's longitude value +const longitude = spatialResults.Longitude; // The entity's longitude value +`} + + + + + + + +## Spatial API + +#### spatial + + + + +{`spatial(fieldName, clause); +spatial(field, clause); +`} + + + +| Parameters | Type | Description | +|---------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in an index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __clause__ | `(SpatialCriteriaFactory) => SpatialCrieteria` | Spatial criteria that will be executed on a given spatial field. | + +#### DynamicSpatialField + + + + +{`class PointField \{ + latitude; + longitude; +\} + +class WktField \{ + wkt; +\} +`} + + + +| Parameters | Type | Description | +|---------------|----------|---------------------------------------------------------| +| __latitude__ | `string` | Path to the document field that contains the latitude | +| __longitude__ | `string` | Path to the document field that contains the longitude | +| __wktPath__ | `string` | Path to the document field that contains the WKT string | + +#### SpatialCriteriaFactory + + + + +{`relatesToShape(shapeWkt, relation); +relatesToShape(shapeWkt, relation, units, distErrorPercent); +intersects(shapeWkt); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, distErrorPercent); +intersects(shapeWkt, units, distErrorPercent); +contains(shapeWkt); +contains(shapeWkt, units); +contains(shapeWkt, distErrorPercent); +contains(shapeWkt, units, distErrorPercent); +disjoint(shapeWkt); +disjoint(shapeWkt, units); +disjoint(shapeWkt, distErrorPercent); +disjoint(shapeWkt, units, distErrorPercent); +within(shapeWkt); +within(shapeWkt, units); +within(shapeWkt, distErrorPercent); +within(shapeWkt, units, distErrorPercent); +withinRadius(radius, latitude, longitude); +withinRadius(radius, latitude, longitude, radiusUnits); +withinRadius(radius, latitude, longitude, radiusUnits, distErrorPercent); +`} + + + +| Parameter | Type | Description | +|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| __relation__ | `string` | Relation of the shape to the spatial data in the document/index.
Can be `Within`, `Contains`, `Disjoint`, `Intersects`. | +| __distErrorPercent__ | `number` | Maximum distance error tolerance in percents. Default: 0.025 | +| __radius__ / __latitude__ / __longitude__ | `number` | Used to define a radius of a circle | +| __radiusUnits__ / __units__ | `string` | Determines if circle or shape should be calculated in `Kilometers` or `Miles`.
By default, distances are measured in kilometers. | + +#### orderByDistance + + + + +{`orderByDistance(field, latitude, longitude); +orderByDistance(field, shapeWkt); +orderByDistance(fieldName, latitude, longitude); +orderByDistance(fieldName, latitude, longitude, roundFactor: number); +orderByDistance(fieldName, shapeWkt); +`} + + + +#### orderByDistanceDescending + + + + +{`orderByDistanceDescending(field, latitude, longitude); +orderByDistanceDescending(field, shapeWkt); +orderByDistanceDescending(fieldName, latitude, longitude); +orderByDistanceDescending(fieldName, latitude, longitude, roundFactor); +orderByDistanceDescending(fieldName, shapeWkt); +`} + + + +| Parameter | Type | Description | +|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | `string` | Path to spatial field in index
(when querying an index). | +| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,
either `PointField` or `WktField`
(when making a dynamic query). | +| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. | +| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured | +| __roundFactor__ | `number` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx new file mode 100644 index 0000000000..783b4dbee8 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx @@ -0,0 +1,537 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents that contain spatial data can be queried by spatial queries that employ geographical criteria. + You can use either _Dynamic spatial query_ or _Spatial index query_. + + * **Dynamic spatial query** + Make a dynamic spatial query on a collection (described below). + An auto-index will be created by the server. + + * **Spatial index query** + Index your documents' spatial data in a static-index (see [indexing spatial data](../../../indexes/indexing-spatial-data.mdx)) + and then make a spatial query on this index (see [query a spatial index](../../../indexes/querying/spatial.mdx)). + +* To perform a spatial search, + use the `spatial` method, which provides a wide range of spatial functionalities. + +* When making a dynamic spatial query from Studio, + results are also displayed on the global map. See [spatial queries map view](../../../studio/database/queries/spatial-queries-map-view.mdx). +* In this page: + + * [Search by radius](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius) + * [Search by shape](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape) + * [Circle](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#circle) + * [Polygon](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#polygon) + * [Spatial sorting](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting) + * [Order by distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance) + * [Order by distance descending](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#order-by-distance-descending) + * [Sort results by rounded distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#sort-results-by-rounded-distance) + * [Get resulting distance](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#get-resulting-distance) + * [Spatial API](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-api) + * [`spatial`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section) + * [`DynamicSpatialField`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-1) + * [`SpatialCriteria`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-2) + * [`order_by_distance`, `order_by_distance_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-3) + * [`order_by_distance_descending`, `order_by_distance_descending_wkt`](../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#section-4) + + +## Search by radius + +Use the `within_radius` method to search for all documents containing spatial data that is located +within the specified distance from the given center point. + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_radius = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical area in which to search for matching documents + # Call 'within_radius', pass the radius and the center points coordinates + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +`} + + + + + + +## Search by shape + +* Use the `relates_to_shape` method to search for all documents containing spatial data that is located + in the specified relation to the given shape. + +* The shape is specified as either a **circle** or a **polygon** in a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. + +* The relation to the shape can be one of: `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS`. +#### Circle + + + + +{`# This query will return all matching employee entities +# that are located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude). + +# Define a query on Employees collection +employees_within_shape = list( + session.query(object_type=Employee) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="CIRCLE(-122.3060097 47.623473 d=20)", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + # Optional: customize radius units (default is Kilometers) + units=SpatialUnits.MILES, + ), + ) +) +`} + + + + +{`// This query will return all matching employee entities +// that are located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("CIRCLE(-122.3060097 47.623473 d=20)", "miles") +) +`} + + + +#### Polygon + + + + +{`# This query will return all matching company entities +# that are located within the specified polygon. + +# Define a query on Companies collection +companies_within_shape = list( + session.query(object_type=Company) + # Call 'spatial' method + .spatial( + # Create 'PointField' + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Set the geographical search criteria, call 'relates_to_shape' + lambda criteria: criteria.relates_to_shape( + # Specify the WKT string. Note: longitude is written FIRST + shape_wkt="""POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894 + ))""", + # Specify the relation between the WKT shape and the documents spatial data + relation=SpatialRelation.WITHIN, + ), + ) +) +`} + + + + +{`// This query will return all matching company entities +// that are located within the specified polygon. + +from companies +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.wkt("POLYGON (( + -118.6527948 32.7114894, + -95.8040242 37.5929338, + -102.8344151 53.3349629, + -127.5286633 48.3485664, + -129.4620208 38.0786067, + -118.7406746 32.7853769, + -118.6527948 32.7114894))") +) +`} + + + + + + +* The polygon's coordinates must be provided in counterclockwise order. + +* The first and last coordinates must mark the same location to form a closed region. + +![WKT polygon](../assets/spatial_1.png) + + + + + +## Spatial sorting + +* Use `order_by_distance` or `order_by_distance_descending` to sort the results by distance from a given point. + +* By default, distance is measured by RavenDB in **kilometers**. + The distance can be rounded to a specific range. +#### Order by distance + + + + +{`# Return all matching employee entities located within 20 kilometers radius +# from point (47.623473 latitude, -122.3060097 longitude) + +# Sort the results by their distance from a specified point, +# the closest results will be listed first. + +employees_sorted_by_distance = list( + session.query(object_type=Employee) + # Provide the query criteria: + .spatial( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + lambda criteria: criteria.within_radius(20, 47.623473, -122.3060097), + ) + # Call 'order_by_distance' + .order_by_distance( + PointField("Address.Location.Latitude", "Address.Location.Longitude"), 47.623473, -122.3060097 + ) +) +`} + + + + +{`// Return all matching employee entities located within 20 kilometers radius +// from point (47.623473 latitude, -122.3060097 longitude). + +// Sort the results by their distance from a specified point, +// the closest results will be listed first. + +from Employees +where spatial.within( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.circle(20, 47.623473, -122.3060097) +) +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) +`} + + + +#### Order by distance descending + + + + +{`# Return all employee entities sorted by their distance from a specified point. +# The farthest results will be listed first. + +employees_sorted_by_distance_desc = list( + session.query(object_type=Employee) + # Call 'order_by_distance_descending' + .order_by_distance_descending( + # Pass the path to document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude"), + # Sort the results by their distance (descending) from this point: + 47.623473, + -122.3060097, + ) +) +`} + + + + +{`// Return all employee entities sorted by their distance from a specified point. +// The farthest results will be listed first. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097) +) desc +`} + + + +#### Sort results by rounded distance + + + + +{`# Return all employee entities. +# Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +# A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +employees_sorted_by_rounded_distance = list( + session.query(object_type=Employee) + # Call 'order_by_distance' + .order_by_distance( + # Pass the path to the document fields containing the spatial data + PointField("Address.Location.Latitude", "Address.Location.Longitude") + # Round up distance to 100 km + .round_to(100), + # Sort the results by their distance from this point: + 47.623473, + -122.3060097, + ).order_by( + "LastName" + ) +) + +pass + +o: +gion spatial_7 +spatial( +self, +field_name_or_field: Union[str, DynamicSpatialField], +clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +.. +`} + + + + +{`// Return all employee entities. +// Results are sorted by their distance to a specified point rounded to the nearest 100 km interval. +// A secondary sort can be applied within the 100 km range, e.g. by field LastName. + +from Employees +order by spatial.distance( + spatial.point(Address.Location.Latitude, Address.Location.Longitude), + spatial.point(47.623473, -122.3060097), + 100 +), LastName +`} + + + +#### Get resulting distance + +* The distance is available in the `@spatial` metadata property within each result. +* Note the following difference between the underlying search engines: + * When using **Lucene**: + This metadata property is always available in the results. + * When using **Corax**: + In order to enhance performance, this property is not included in the results by default. + To get this metadata property you must set the [Indexing.Corax.IncludeSpatialDistance](../../../server/configuration/indexing-configuration.mdx#indexingcoraxincludespatialdistance) configuration value to _true_. + Learn about the available methods for setting an indexing configuration key in this [indexing-configuration](../../../server/configuration/indexing-configuration.mdx) article. + + + +{`# Get the distance of the results: +# ================================ + +# Call 'get_metadata_for', pass an entity from the resulting employees list +metadata = session.advanced.get_metadata_for(employees_sorted_by_distance[0]) + +# The distance is available in the '@spatial' metadata property +spatial_results = metadata["@spatial"] + +distance = spatial_results["Distance"] # The distance of the entity from the queried location +latitude = spatial_results["Latitude"] # The entity's latitude value +longitude = spatial_results["Longitude"] # The entity's longitude value +`} + + + + + +## Spatial API + +#### `spatial` + + + +{`def spatial( + self, + field_name_or_field: Union[str, DynamicSpatialField], + clause: Callable[[SpatialCriteriaFactory], SpatialCriteria], +): ... +`} + + + +| Parameters | Type | Description | +|---------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| **field_name_or_field** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **clause** | `Callable[[SpatialCriteriaFactory], SpatialCriteria]` | Callback taking leverage of SpatialCriteriaFactory that comes as an argument, allowing to build SpatialCriteria. | +#### `DynamicSpatialField` + + + +{`class PointField(DynamicSpatialField): + def __init__(self, latitude: str, longitude: str): ... + +class WktField(DynamicSpatialField): + def __init__(self, wkt: str): ... +`} + + + +| Parameters | Type | Description | +|---------------|-------|-----------------------------------------------------------| +| **latitude** | `str` | Path to a document point field that contains the latitude | +| **longitude** | `str` | Path to a document point field that contains the longitude | +| **wkt** | `str` | Path to a document wkt field that contains the WKT string | +#### `SpatialCriteria` + + + +{`def relates_to_shape( + self, + shape_wkt: str, + relation: SpatialRelation, + units: SpatialUnits = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def intersects( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def contains( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def disjoint( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within( + self, + shape_wkt: str, + units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... + +def within_radius( + self, + radius: float, + latitude: float, + longitude: float, + radius_units: Optional[SpatialUnits] = None, + dist_error_percent: Optional[float] = constants.Documents.Indexing.Spatial.DEFAULT_DISTANCE_ERROR_PCT, +) -> SpatialCriteria: ... +`} + + + +| Parameter | Type | Description | +|---------------|-------|--------------------| +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | +| **relation** | `SpatialRelation` | Relation of the shape to the spatial data in the document/index.
Can be `WITHIN`, `CONTAINS`, `DISJOINT`, `INTERSECTS` | +| **units** / **radius_units** | `SpatialUnits` | Determines if circle or shape should be calculated in `KILOMETERS` or `MILES`.
By default, distances are measured in kilometers. | +| **dist_error_percent** (Optional) | `float` | Maximum distance error tolerance in percents.
**Default: 0.025** | +| **radius** / **latitude** / **longitude** | `float` | Used to define a radius of a circle | +#### `order_by_distance`, `order_by_distance_wkt` + + + +{`# From point & rounding + +def order_by_distance( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + +#### `order_by_distance_descending`, `order_by_distance_descending_wkt` + + + +{`# From point & rounding + +def order_by_distance_descending( + self, + field_or_field_name: Union[str, DynamicSpatialField], + latitude: float, + longitude: float, + round_factor: Optional[float] = 0.0, +) -> DocumentQuery[_T]: ... + +# From center of WKT shape + +def order_by_distance_descending_wkt( + self, field_or_field_name: Union[str, DynamicSpatialField], shape_wkt: str +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)

**-or-**

`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). | +| **latitude** | `float` | The latitude of the point from which the distance is measured | +| **longitude** | `float` | The longitude of the point from which the distance is measured | +| **round_factor** (Optional) | `float` | A distance interval in kilometers.
The distance from the point is rounded up to the nearest interval.
The results within the same interval can be sorted by a secondary order.
If no other order was specified, then by ascending order of document Id. | +| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-a-faceted-search-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-a-faceted-search-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-group-by-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-group-by-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-perform-queries-lazily-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-perform-queries-lazily-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-project-query-results-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-project-query-results-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-stream-query-results-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-stream-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-intersect-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-intersect-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-use-morelikethis-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-use-morelikethis-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx new file mode 100644 index 0000000000..1d4b9221d7 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-csharp.mdx @@ -0,0 +1,621 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for single term: +// ========================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':"); +foreach (string suggestedTerm in suggestions["Name"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("Name") +{ + // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof' + Terms = new[] { "chaig", "tof"} +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .ByField(x => x.Name, new[] { "chaig", "tof" })) + .Execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to 'chop-soy china' + Term = "chop-soy china" +}; + +var request2 = new SuggestionWithTerm("Contact.Name") +{ + // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' + Term = "maria larson" +}; + +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .AndSuggestUsing(builder => builder + .ByField(x => x.Contact.Name, "maria larson")) + .Execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("Name") +{ + // Looking for terms from field 'Name' that are similar to term 'chaig' + Term = "chaig", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.Name, "chaig") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.4f, + PageSize = 5, + Distance = StringDistanceTypes.JaroWinkler, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Overloads for requesting suggestions for term(s) in a field: +ISuggestionQuery SuggestUsing(SuggestionBase suggestion); +ISuggestionQuery SuggestUsing(Action> builder); + +// Overloads requesting suggestions for term(s) in another field in the same query: +ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); +ISuggestionQuery AndSuggestUsing(Action> builder); +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`ISuggestionOperations ByField(string fieldName, string term); +ISuggestionOperations ByField(string fieldName, string[] terms); +ISuggestionOperations ByField(Expression> path, string term); +ISuggestionOperations ByField(Expression> path, string[] terms); + +ISuggestionOperations WithDisplayName(string displayName); +ISuggestionOperations WithOptions(SuggestionOptions options); +`} + + + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **path** | `Expression>` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). | + +**Suggestions options**: + + + +{`public int PageSize \{ get; set; \} +public StringDistanceTypes? Distance \{ get; set; \} +public float? Accuracy \{ get; set; \} +public SuggestionSortMode SortMode \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------------------|-------------| +| **PageSize** | `int` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **Distance** | `StringDistanceTypes` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **Accuracy** | `float?` |
  • Suggestion accuracy.
  • Default is 0.5f
| +| **SortMode** | `SuggestionSortMode` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_how-to-work-with-suggestions-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx new file mode 100644 index 0000000000..ee64df0f6a --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-nodejs.mdx @@ -0,0 +1,358 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the **Northwind sample data**, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`// This dynamic query on the 'Products' collection has NO resulting documents +const products = await session + .query(\{ collection: "Products" \}) + .whereEquals("Name", "Chai") + .all(); +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`// Query for suggested terms for single term: +// ========================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' + .byField("Name", "chaig")) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in field 'Name' that are similar to 'chaig':"); +suggestions["Name"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in field 'Name' that are similar to 'chaig': +// chai +// chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query for suggested terms for multiple terms: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' + .byField("Name", ["chaig", "tof"])) + .execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +// chai +// chang +// tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query for suggested terms in multiple fields: +// ============================================= + +const suggestions = await session + // Make a dynamic query on collection 'Companies' + .query({ collection: "Companies" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chop-soy china' in first document field (e.g. 'Name') + .suggestUsing(x => x + .byField("Name", "chop-soy china")) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .andSuggestUsing(x => x + .byField("Contact.Name", "maria larson")) + .execute(); +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in field 'Name' that is similar to 'chop-soy china': +// chop-suey chinese + +// Suggested terms in field 'Contact.Name' that are similar to 'maria larson': +// maria larsson +// marie bertrand +// aria cruz +// paula wilson +// maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query for suggested terms - customize options and display name: +// =============================================================== + +const suggestions = await session + // Make a dynamic query on collection 'Products' + .query({ collection: "Products" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("Name", "chaig") + // Customize suggestions options + .withOptions({ + accuracy: 0.4, + pageSize: 5, + distance: "JaroWinkler", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chai +// chang +// chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`// Requesting suggestions for term(s) in a field: +suggestUsing(action); + +// Requesting suggestions for term(s) in another field in the same query: +andSuggestUsing(action); +`} + + + +| Parameter | Type | Description | +|-------------|---------------------|---------------------------------------------------------------------------------| +| **action** | `(builder) => void` | Builder function with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`byField(fieldName, term); +byField(fieldName, terms); + +withDisplayName(displayName); +withOptions(options); +`} + + + +| Parameter | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index field in which to search for similar terms | +| **term** | `string` | The term for which to get suggested similar terms | +| **terms** | `string[]` | List of terms for which to get suggested similar terms | +| **displayName** | `string` | A custom name for the suggestions result (optional). | +| **options** | `object` | Non-default suggestion options to use in the operation (optional).
See available options below. | + +**Suggestions options**: + +| Option | Type | Description | +|--------------|----------|-------------| +| **pageSize** | `number` |
  • Maximum number of suggested terms that will be returned.
  • Default is 15
| +| **distance** | `string` |
  • String distance algorithm to use.
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein.
| +| **accuracy** | `number` |
  • Suggestion accuracy.
  • Default is 0.5
| +| **sortMode** | `string` |
  • Indicates the order by which results are returned.
  • `None` / `Popularity`
  • Default is Popularity.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx new file mode 100644 index 0000000000..8945b1b6d5 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-php.mdx @@ -0,0 +1,270 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for a single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for a single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + + +{`$options = new SuggestionOptions(); +$options->setAccuracy(0.4); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::jaroWinkler()); +$options->setSortMode(SuggestionSortMode::popularity()); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing(function($builder) use ($options) { + $builder->byField("FullName", "johne") + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +## Suggest terms - for multiple terms + + + + +{`private int $pageSize = 15; +private ?StringDistanceTypes $distance = null; +private float $accuracy = 0.5; +private ?SuggestionSortMode $sortMode = null; + +public function __construct() +{ + $distance = StringDistanceTypes::levenshtein(); + $sortMode = SuggestionSortMode::popularity(); + ... +} + +// getters and setters for fields listed above +`} + + + + +{`$suggestionWithTerm = new SuggestionWithTerm("FullName"); +$suggestionWithTerm->setTerm("johne"); + +/** @var array $suggestions */ +$suggestions = $session + ->query(Employee::class, Employees_ByFullName::class) + ->suggestUsing($suggestionWithTerm) + ->execute(); +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`/** + * Usage: + * - suggestUsing(SuggestionBase $suggestion); + * - suggestUsing(Closure $suggestionBuilder); + * + * @param SuggestionBase|Closure|null $suggestionOrBuilder + * @return SuggestionDocumentQueryInterface + */ +public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------| +| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +**Builder operations**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Parameter | Type | Description | +|-----------------|---------------------------------|------------------------------------------------------| +| **$fieldName** | `?string` | The index field in which to search for similar terms | +| **$terms** | `null`
`string`
`StringArray`
`array` | List of terms to get suggested similar terms for | +| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) | + +**Suggestions options**: + + + +{`/** + * Usage: + * - byField("fieldName", "term"); + * - byField("fieldName", ["term1", "term2"]); + */ +function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface; + +function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface; +`} + + + +| Option | Type | Description | +|--------------|-------------------------|---------------------------------------------| +| **$pageSize** | `int` | Maximum number of suggested terms to return | +| **$distance** | `?StringDistanceTypes` | String distance algorithm to use | +| **$accuracy** | `float` | Suggestion accuracy | +| **$sortMode** | `?SuggestionSortMode` | Order to return results by | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx new file mode 100644 index 0000000000..f0354dff46 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/content/_how-to-work-with-suggestions-python.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Given a string term, the Suggestion feature will offer **similar terms** from your data. + +* Word similarities are found using string distance algorithms. + +* Examples in this article demonstrate getting suggestions with a **dynamic-query**. + For getting suggestions with an **index-query** see [query for suggestions with index](../../../indexes/querying/suggestions.mdx). +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax) + + +## What are terms + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + Whether making a dynamic query which generates an auto-index or using a static index, + the data from your documents is 'broken' into **terms** that are kept in the index. + +* This tokenization process (what terms will be generated) depends on the analyzer used, + various analyzers differ in the way they split the text stream. Learn more in [Analyzers](../../../indexes/using-analyzers.mdx). + +* The terms can then be queried to retrieve matching documents that contain them. + + + +## When to use suggestions + +Querying for suggestions is useful in the following scenarios: + + * **When query has no results**: + + * When searching for documents that match some condition on a given string term, + if the term is misspelled then you will Not get any results. + You can then ask RavenDB to suggest similar terms that do exist in the index. + + * The suggested terms can then be used in a new query to retrieve matching documents, + or simply presented to the user asking what they meant to query. + + * **When looking for alternative terms**: + + * When simply searching for additional alternative terms for a term that does exist. + + + +The resulting suggested terms will Not include the term for which you search, +they will only contain the similar terms. + + + + + +## Suggest terms - for single term + +Consider this example: +Based on the Northwind sample data, the following query has no resulting documents, +as no document in the Products collection contains the term `chaig` in its `Name` field. + + + +{`# This dynamic query on the 'Products' collection has NO documents +products = list(session.query(object_type=Product).where_equals("name", "chaig")) +`} + + + +* Executing the above query will generate the auto-index `Auto/Products/ByName`. + This auto-index will contain a list of all available terms from the document field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions.mdx#the-auto-index-terms-in-studio). + +* If you suspect that the term `chaig` in the query criteria is written incorrectly, + you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:. + + + + +{`# Query for suggested terms for single term: +# ========================================== +suggestions = ( + session.query(object_type=Product) + .suggest_using(lambda builder: builder.by_field("name", "chaig")) + .execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("name") +suggestion_request.term = "chaig" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' +from "Products" +select suggest(Name, "chaig") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in field 'name' that are similar to 'chaig':") +for suggested_term in suggestions["name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in field 'Name' that are similar to 'chaig': +# chai +# chang +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query for suggested terms for multiple terms: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from field 'name' that are similar to 'chaig' OR 'tof' + .by_field("name", ["chaig", "tof"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("name") +# Looking for terms from field 'name' that are similar to 'chaig' OR 'tof' +suggestion_request.terms = ["chaig", "tof"] + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' +from "Products" select suggest(Name, $p0) +{ "p0" : ["chaig", "tof"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': +# chai +# chang +# tofu +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query for suggested terms in multiple fields: +# ============================================= + +suggestions = ( + session + # Make a dynamic query on collection 'Companies' + .query(object_type=Company) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chop-soy china' in first document field (e.g. 'name') + .suggest_using(lambda builder: builder.by_field("name", "chop-soy china")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'maria larson' in an additional field (e.g. 'Contact.Name') + .and_suggest_using(lambda builder: builder.by_field("contact.name", "maria larson")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to 'chop-soy china' +request1.term = "chop-soy china" + +request2 = SuggestionWithTerm("contact.name") +# Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson' +request2.term = ["maria larson"] + +suggestions = ( + session.query(object_type=Company) + # Call 'suggest_using' - pass the suggestion request for the first field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second field + .and_suggest_using(request2).execute() +) +`} + + + + +{`// Query for suggested terms from field 'Name' and field 'Contact.Name' +from "Companies" +select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== +# +# Suggested terms in field 'name' that is similar to 'chop-soy china': +# chop-suey chinese +# +# Suggested terms in field 'contact.name' that are similar to 'maria larson': +# maria larsson +# marie bertrand +# aria cruz +# paula wilson +# maria anders +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query for suggested terms - customize options and display name: +# =============================================================== +suggestions = ( + session + # Make a dynamic query on collection 'Products' + .query(object_type=Product) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("name", "chaig") + # Customize suggestion options + .with_options( + SuggestionOptions( + accuracy=0.4, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("name") +# Looking for terms from field 'Name' that are similar to term 'chaig' +suggestion_request.term = "chaig" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=5, + page_size=5, + distance=StringDistanceTypes.JARO_WINKLER, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query for suggestions +suggestions = ( + session.query(object_type=Product) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from "Products" +select suggest( + Name, + 'chaig', + '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chai +# chang +# chartreuse verte +`} + + + + + +## The auto-index terms in Studio + +Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`: + +![Figure 1. Auto-index terms](../assets/auto-index-terms.png) + +1. **The field name** - derived from the document field that was used in the dynamic-query. + In this example the field name is `Name`. + +2. **The terms** generated from the data that the Products collection documents have in their `Name` field. + + + +## Syntax + +**Suggest using**: + + + +{`# Method for requesting suggestions for term(s) in a field: +def suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... + +# Method for requesting suggestions for term(s) in another field in the same query: +def and_suggest_using( + self, suggestion_or_builder: Union[SuggestionBase, Callable[[SuggestionBuilder[_T]], None]] +) -> SuggestionDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|----------------|----------------------------------------------|--------------| +| **suggestion_or_builder**
(Union) | `SuggestionBase`| **Suggestion instance**
Pass `suggest_using` a `SuggestionBase` instance with the term or terms (`SuggestionWithTerm` or `SuggestionWithTerms`) it will generate suggestions by. | +| | `Callable[[SuggestionBuilder[_T]], None]` | **Suggestion builder**
Use `suggest_using`'s fluent API to pass it a method that takes `SuggestionBuilder` as a parameter and generate a suggestion definition that matches your needs. | + +| Return type | Description | +|----------------|--------------| +| `SuggestionDocumentQuery[_T]` | The generated suggestions query, that can now be executed using `execute()` or further altered.
When `execute()` is called, it will return the suggestions in a `Dict[str, SuggestionResult]` dictionary. | + + +**Builder operations**: + + + +{`def by_field(self, field_name: str, term_or_terms: Union[str, List[str]]) -> SuggestionOperations[_T]: ... + +def with_display_name(self, display_name: str) -> SuggestionOperations[_T]: ... +def with_options(self, options: SuggestionOptions) -> SuggestionOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|-----------------|--------------------------------|---------------------------------------------| +| **field_name** | `str` | The index field to search for similar terms | +| **term_or_terms** (Union) | `str` or `List[str]` | Term or List of terms to get suggested similar terms for | +| **display_name** | `str` | A custom name for the suggestions result | +| **options** | `SuggestionOptions` | Non-default options to use in the operation | + +**Suggestion options**: + + + +{`DEFAULT_ACCURACY = 0.5 +DEFAULT_PAGE_SIZE = 15 +DEFAULT_DISTANCE = StringDistanceTypes.LEVENSHTEIN +DEFAULT_SORT_MODE = SuggestionSortMode.POPULARITY + +def __init__( + self, + page_size: int = DEFAULT_PAGE_SIZE, + distance: StringDistanceTypes = DEFAULT_DISTANCE, + accuracy: float = DEFAULT_ACCURACY, + sort_mode: SuggestionSortMode = DEFAULT_SORT_MODE, +): + self.page_size = page_size + self.distance = distance + self.accuracy = accuracy + self.sort_mode = sort_mode +`} + + + +| Parameter | Type | Description | +|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------| +| **page_size** | `int` | Maximum number of suggested terms that will be returned
Default: **15** | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE` / `LEVENSHTEIN` / `JAROWINKLER` / `NGRAM`)
Default: **LEVENSHTEIN** | +| **accuracy** | `float` | Suggestion accuracy
Default: **0.5** | +| **sort_mode** | `SuggestionSortMode` | Indicates the order by which results are returned (`NONE` / `POPULARITY`)
Default: **POPULARITY** | diff --git a/versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_sort-query-results-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_sort-query-results-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/_vector-search-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/content/_vector-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/_vector-search-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/content/_vector-search-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx deleted file mode 100644 index ced793543f..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-csharp.mdx +++ /dev/null @@ -1,159 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* **To get the score details** and see how it was calculated, - use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`var products = session - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`var products = await asyncSession - .Query() - // Convert the IRavenQueryable to IDocumentQuery - // to be able to use 'IncludeExplanations' - .ToAsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Convert back to IRavenQueryable - // to continue building the query using LINQ - .ToQueryable() - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`DocumentQuery\` -var products = session.Advanced - .DocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`// Query with \`AsyncDocumentQuery\` -var products = await asyncSession.Advanced - .AsyncDocumentQuery() - // Call IncludeExplanations, provide an out param for the explanations results - .IncludeExplanations(out Explanations explanations) - // Define query criteria - // e.g. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get the score details for a specific document from the results -// Call GetExplanations on the resulting Explanations object -string[] scoreDetails = explanations.GetExplanations(products[0].Id); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`IDocumentQuery IncludeExplanations(out Explanations explanations); -`} - - - -| Parameter | Type | Description | -|------------------|----------------|------------------------------------------------------------------| -| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | - -| `Explanations` | Description | -|------------------------------------------|-------------| -| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-nodejs.mdx deleted file mode 100644 index 6c818a97a8..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-nodejs.mdx +++ /dev/null @@ -1,105 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* This article provides examples of including explanations when making a **dynamic-query**. - For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`// Define an object that will receive the explanations results -let explanationsResults; - -const products = await session.query({ collection: "Products" }) - // Call includeExplanations, pass a callback function - // Output param 'explanationsResults' will be filled with explanations results when query returns - .includeExplanations(e => explanationsResults = e) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get the score details for a specific document from 'explanationsResults' -const id = session.advanced.getDocumentId(products[0]); -const scoreDetails = explanationsResults.explanations[id]; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. -* Running a query with `include explanations()` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`query.includeExplanations(explanationsCallback) -`} - - - -| Parameter | Type | Description | -|--------------------------|---------------------------------|-------------| -| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| - - - -{`// The Explanations object: -// ======================== - -class Explanations \{ - get explanations(): \{ - [key: string]: string[]; // An explanations list per document ID key - \}; -\} -`} - - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-php.mdx deleted file mode 100644 index a875c9f1c3..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-php.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `includeExplanations` to get the score details and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - -## Include explanations in a query - - - - -{`$explanations = new Explanations(); - -/** @var array $syrups */ -$syrups = $session->advanced()->documentQuery(Product::class) - ->includeExplanations(null, $explanations) - ->search("Name", "Syrup") - ->toList(); - -$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - -Please note that the First parameter is optional. -If you intend to use the default options, just paste `null` instead of the options object. - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `includeExplanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-----------------------|-------------| -| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | -| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-python.mdx deleted file mode 100644 index 576dcfe967..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-python.mdx +++ /dev/null @@ -1,102 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, each document in the query results is assigned a **score**. - This score determines the order by which the documents come back in the results when requesting - to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). - -* Each document in the results includes this score under the `@index-score` property in its metadata. - -* Use `include_explanations` to get the score details** and see how it was calculated. - - - * Including explanations is available only when using **Lucene** as the underlying search engine. - * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). - -* In this page: - * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) - * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) - * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) - - -## Include explanations in a query - - - - -{`# Prepare a callback -explanations_results: Optional[Explanations] = None - -def explanations_callback(explanations: Explanations): - explanations_results = explanations - -# Query with 'document_query' - -# Execute the query -results = list( - # Prepare a query - session.advanced.document_query(object_type=Product) - # Call include_expirations, provide an out param for the explanations results - .include_explanations() - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") -) - -# Get the score details for a specific document from the results -# Get explanations from the resulting Explanations object -score_details = explanations_results.explanations[results[0].Id] -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include explanations() -`} - - - - - - -## View explanations - -* The detailed explanations can be viewed from the **Query view** in Studio. - -* Running a query with `include_explanations` will show an additional **Explanations Tab**. - -![Figure 1. Explanations in the Studio](./assets/include-explanations-1.png) - -* Sample score details: - -![Figure 2. View explanations](./assets/include-explanations-2.png) - - - -## Syntax - - - -{`def include_explanations( - self, - options: Optional[ExplanationOptions] = None, - explanations_callback: Callable[[Explanations], None] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|---------------------------|----------------------------------|-------------| -| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| -| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | - -| `Explanations` | Description | -|------------------------|-------------| -| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-csharp.mdx deleted file mode 100644 index 90c08b9c95..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-csharp.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = session.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`// Define an object that will receive the query timings -QueryTimings timings = null; - -var results = await asyncSession.Query() - // Use the Customize method to Call Timings, provide an out param for the timings results - .Customize(x => x.Timings(out timings)) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = session.Advanced.DocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToList(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`var results = await asyncSession.Advanced.AsyncDocumentQuery() - // Call Timings, provide an out param for the timings results - .Timings(out QueryTimings timings) - // Define the search criteria - // Search for docs containing Syrup -or- Lager in their Name field - .Search(x => x.Name, "Syrup Lager") - // Execute the query - .ToListAsync(); - -// Get total query duration: -// ========================= -var totalQueryDuration = timings.DurationInMs; - -// Get specific parts duration: -// ============================ -IDictionary timingsDictionary = timings.Timings; -var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; -var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization Timings(out QueryTimings timings); -`} - - - -| Parameter | Type | Description | -|-------------|----------------|-------------------------------------------------------------| -| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| __DurationInMs__ | `long` | Total duration | -| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-java.mdx deleted file mode 100644 index 82050a7150..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-java.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`Reference timingsRef = new Reference<>(); -List resultsWithTimings = session.advanced().documentQuery(Product.class) - .timings(timingsRef) - .search("Name", "Syrup") - .toList(); - -Map timingsMap = timingsRef.value.getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`IDocumentQueryCustomization timings(Reference timings); -`} - - - -The `QueryTimings` object will be filled with the timings when the query returns. - -| `QueryTimings` | | | -|------------------|-----------------------------|---------------------------------------------------| -| __durationInMs__ | `long` | Total duration | -| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-nodejs.mdx deleted file mode 100644 index 2594955761..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-nodejs.mdx +++ /dev/null @@ -1,106 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* __To include the query timings__ in the query results: - add a call to `timings()` in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`// Define an object that will receive the timings results -let timingsResults; - -const results = await session.query({ collection: "Products" }) - // Call timings, pass a callback function - // Output param 'timingsResults' will be filled with the timings details when query returns - .timings(t => timingsResults = t) - // Define query criteria - // i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - // Execute the query - .all(); - -// Get total query duration: -// ========================= -const totalQueryDuration = timingsResults.durationInMs; - -// Get specific parts duration: -// ============================ -const optimizerDuration = timingsResults.timings.optimizer.durationInMs; -// or: timingsResults.timings["optimizer"].durationInMs; -const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; -// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional __Timings Tab__ - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`query.timings(timingsCallback) -`} - - - -| Parameter | Type | Description | -|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | - -| `QueryTimings` | | | -|------------------|--------------------------------|---------------------------------------------------| -| __durationInMs__ | `number` | Total duration | -| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided __per shard__. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-php.mdx deleted file mode 100644 index 447455323e..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-php.mdx +++ /dev/null @@ -1,88 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`$timings = new QueryTimings(); - -/** @var array $resultsWithTimings */ -$resultsWithTimings = $session->advanced()->documentQuery(Product::class) - ->timings($timings) - ->search("Name", "Syrup") - ->toList(); - -/** @var array $timingsMap */ -$timingsMap = $timings->getTimings(); -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`function timings(QueryTimings &$timings): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-python.mdx deleted file mode 100644 index a24ff39584..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/_query-timings-python.mdx +++ /dev/null @@ -1,118 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a query, - you can request to get detailed stats of the time spent by RavenDB on each part of the query. - E.g. duration of search, loading documents, transforming results, total duration, etc. - -* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. - -* **To include the query timings** in the query results: - add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. - See examples below. - -* In this page: - * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) - * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) - * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) - * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) - - -## Include timings in a query - - - - -{`timings: Optional[QueryTimings] = None - -# Prepare a callback -def timings_callback(timings_from_server: QueryTimings): - timings = timings_from_server - -results = list( - session.advanced.document_query(object_type=Product) - # Call timings, provide a callback function that will be called with result timings - .timings(timings_callback) - # Define query criteria - # i.e. search for docs containing Syrup -or- Lager in their Name field - .search("Name", "Syrup Lager") - # Execute the query -) - -# Get total query duration: -# ========================= -total_query_duration = timings.duration_in_ms - -# Get specific parts duration: -# ============================ -timings_dictionary = timings.timings -optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms -lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms -`} - - - - -{`from "Products" -where search(Name, "Syrup") or search(Name, "Lager") -include timings() -`} - - - - - - -## View timings - -* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. - -* Running an RQL query with `include timings()` will show an additional **Timings Tab** - with a graphical representation of the time spent in each query part. - -![Figure 1. Include timings graphical results](./assets/include-timings.png) - - - -## Syntax - - - -{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|-------------|----------------|---------------| -| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | - - - -{`class QueryTimings: - def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): - self.duration_in_ms = duration_in_ms - self.timings = timings or \{\} -`} - - - -| `QueryTimings` | | | -|------------------|-------------------------------------|---------------------------------------------------| -| **duration_in_ms** | `int` | Total duration | -| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | - - - -## Timings in a sharded database - -* In a sharded database, timings for each part are provided **per shard**. - -* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx new file mode 100644 index 0000000000..54a96307a9 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-csharp.mdx @@ -0,0 +1,159 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* **To get the score details** and see how it was calculated, + use method `IncludeExplanations`, which is available in the [IDocumentQuery](../../../../client-api/session/querying/document-query/what-is-document-query.mdx) interface. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`var products = session + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`var products = await asyncSession + .Query() + // Convert the IRavenQueryable to IDocumentQuery + // to be able to use 'IncludeExplanations' + .ToAsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Convert back to IRavenQueryable + // to continue building the query using LINQ + .ToQueryable() + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`DocumentQuery\` +var products = session.Advanced + .DocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`// Query with \`AsyncDocumentQuery\` +var products = await asyncSession.Advanced + .AsyncDocumentQuery() + // Call IncludeExplanations, provide an out param for the explanations results + .IncludeExplanations(out Explanations explanations) + // Define query criteria + // e.g. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get the score details for a specific document from the results +// Call GetExplanations on the resulting Explanations object +string[] scoreDetails = explanations.GetExplanations(products[0].Id); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`IDocumentQuery IncludeExplanations(out Explanations explanations); +`} + + + +| Parameter | Type | Description | +|------------------|----------------|------------------------------------------------------------------| +| **explanations** | `Explanations` | An _out_ param that will be filled with the explanations results | + +| `Explanations` | Description | +|------------------------------------------|-------------| +| `string[] GetExplanations(string docId)` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/debugging/_include-explanations-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx new file mode 100644 index 0000000000..ebdf774b7e --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-nodejs.mdx @@ -0,0 +1,105 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` in your query **to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* This article provides examples of including explanations when making a **dynamic-query**. + For including explanations when querying a **static-index** see [Include explanations in index query](../../../../indexes/querying/include-explanations.mdx). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`// Define an object that will receive the explanations results +let explanationsResults; + +const products = await session.query({ collection: "Products" }) + // Call includeExplanations, pass a callback function + // Output param 'explanationsResults' will be filled with explanations results when query returns + .includeExplanations(e => explanationsResults = e) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get the score details for a specific document from 'explanationsResults' +const id = session.advanced.getDocumentId(products[0]); +const scoreDetails = explanationsResults.explanations[id]; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. +* Running a query with `include explanations()` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`query.includeExplanations(explanationsCallback) +`} + + + +| Parameter | Type | Description | +|--------------------------|---------------------------------|-------------| +| **explanationsCallback** | `(explanationsResults) => void` |
  • A callback function with an output parameter.
  • The parameter passed to the callback will be filled with the `Explanations` object when the query returns.
| + + + +{`// The Explanations object: +// ======================== + +class Explanations \{ + get explanations(): \{ + [key: string]: string[]; // An explanations list per document ID key + \}; +\} +`} + + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-php.mdx new file mode 100644 index 0000000000..e06f0811fb --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-php.mdx @@ -0,0 +1,85 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `includeExplanations` to get the score details and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + +## Include explanations in a query + + + + +{`$explanations = new Explanations(); + +/** @var array $syrups */ +$syrups = $session->advanced()->documentQuery(Product::class) + ->includeExplanations(null, $explanations) + ->search("Name", "Syrup") + ->toList(); + +$scoreDetails = $explanations->getExplanations($syrups[0]->getId()); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + +Please note that the First parameter is optional. +If you intend to use the default options, just paste `null` instead of the options object. + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `includeExplanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-----------------------|-------------| +| **$options** | `?ExplanationOptions` | This object is optional.
If you intend to use the default options, place `null` here. | +| **&$explanations** | `Explanations` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-python.mdx new file mode 100644 index 0000000000..4c6736f39f --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_include-explanations-python.mdx @@ -0,0 +1,102 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, each document in the query results is assigned a **score**. + This score determines the order by which the documents come back in the results when requesting + to [order by score](../../../../client-api/session/querying/sort-query-results.mdx#order-by-score). + +* Each document in the results includes this score under the `@index-score` property in its metadata. + +* Use `include_explanations` to get the score details** and see how it was calculated. + + + * Including explanations is available only when using **Lucene** as the underlying search engine. + * You can configure which search engine will be used. Learn how in [Selecting the search engine](../../../../indexes/search-engine/corax.mdx#selecting-the-search-engine). + +* In this page: + * [Include explanations in a query](../../../../client-api/session/querying/debugging/include-explanations.mdx#include-explanations-in-a-query) + * [View explanations](../../../../client-api/session/querying/debugging/include-explanations.mdx#view-explanations) + * [Syntax](../../../../client-api/session/querying/debugging/include-explanations.mdx#syntax) + + +## Include explanations in a query + + + + +{`# Prepare a callback +explanations_results: Optional[Explanations] = None + +def explanations_callback(explanations: Explanations): + explanations_results = explanations + +# Query with 'document_query' + +# Execute the query +results = list( + # Prepare a query + session.advanced.document_query(object_type=Product) + # Call include_expirations, provide an out param for the explanations results + .include_explanations() + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") +) + +# Get the score details for a specific document from the results +# Get explanations from the resulting Explanations object +score_details = explanations_results.explanations[results[0].Id] +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include explanations() +`} + + + + + + +## View explanations + +* The detailed explanations can be viewed from the **Query view** in Studio. + +* Running a query with `include_explanations` will show an additional **Explanations Tab**. + +![Figure 1. Explanations in the Studio](../assets/include-explanations-1.png) + +* Sample score details: + +![Figure 2. View explanations](../assets/include-explanations-2.png) + + + +## Syntax + + + +{`def include_explanations( + self, + options: Optional[ExplanationOptions] = None, + explanations_callback: Callable[[Explanations], None] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|---------------------------|----------------------------------|-------------| +| **explanations_callback** | `Callable[[Explanations], None]` |
  • A callback function (action) that takes `Explanations` as an argument. It will be called by the client with the resulting `Explanations`.
  • You can interact with the resulting `Explanations` inside your callback.
| +| **options** (Optional) | `ExplanationOptions` | Can be a `group_key` string. | + +| `Explanations` | Description | +|------------------------|-------------| +| `Dict[str, List[str]]` |
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.
| diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx new file mode 100644 index 0000000000..87f6efdabe --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-csharp.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `Timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = session.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`// Define an object that will receive the query timings +QueryTimings timings = null; + +var results = await asyncSession.Query() + // Use the Customize method to Call Timings, provide an out param for the timings results + .Customize(x => x.Timings(out timings)) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = session.Advanced.DocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToList(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`var results = await asyncSession.Advanced.AsyncDocumentQuery() + // Call Timings, provide an out param for the timings results + .Timings(out QueryTimings timings) + // Define the search criteria + // Search for docs containing Syrup -or- Lager in their Name field + .Search(x => x.Name, "Syrup Lager") + // Execute the query + .ToListAsync(); + +// Get total query duration: +// ========================= +var totalQueryDuration = timings.DurationInMs; + +// Get specific parts duration: +// ============================ +IDictionary timingsDictionary = timings.Timings; +var optimizerDuration = timingsDictionary["Optimizer"].DurationInMs; +var luceneDuration = timingsDictionary["Query"].Timings["Lucene"].DurationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization Timings(out QueryTimings timings); +`} + + + +| Parameter | Type | Description | +|-------------|----------------|-------------------------------------------------------------| +| __timings__ | `QueryTimings` | An _out_ param that will be filled with the timings results | + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| __DurationInMs__ | `long` | Total duration | +| __Timings__ | `IDictionary` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-java.mdx new file mode 100644 index 0000000000..dde738eb47 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-java.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`Reference timingsRef = new Reference<>(); +List resultsWithTimings = session.advanced().documentQuery(Product.class) + .timings(timingsRef) + .search("Name", "Syrup") + .toList(); + +Map timingsMap = timingsRef.value.getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`IDocumentQueryCustomization timings(Reference timings); +`} + + + +The `QueryTimings` object will be filled with the timings when the query returns. + +| `QueryTimings` | | | +|------------------|-----------------------------|---------------------------------------------------| +| __durationInMs__ | `long` | Total duration | +| __timings__ | `Map` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx new file mode 100644 index 0000000000..04c49f9a7d --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-nodejs.mdx @@ -0,0 +1,106 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* __To include the query timings__ in the query results: + add a call to `timings()` in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`// Define an object that will receive the timings results +let timingsResults; + +const results = await session.query({ collection: "Products" }) + // Call timings, pass a callback function + // Output param 'timingsResults' will be filled with the timings details when query returns + .timings(t => timingsResults = t) + // Define query criteria + // i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + // Execute the query + .all(); + +// Get total query duration: +// ========================= +const totalQueryDuration = timingsResults.durationInMs; + +// Get specific parts duration: +// ============================ +const optimizerDuration = timingsResults.timings.optimizer.durationInMs; +// or: timingsResults.timings["optimizer"].durationInMs; +const luceneDuration = timingsResults.timings.query.timings.lucene.durationInMs; +// or: timingsResults.timings["query"].timings.["lucene"].durationInMs; +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional __Timings Tab__ + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`query.timings(timingsCallback) +`} + + + +| Parameter | Type | Description | +|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __timingsCallback__ | `(timingsCallback) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the `QueryTimings` object when query returns.</li></ul> | + +| `QueryTimings` | | | +|------------------|--------------------------------|---------------------------------------------------| +| __durationInMs__ | `number` | Total duration | +| __timings__ | `Record` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided __per shard__. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-php.mdx new file mode 100644 index 0000000000..ff61a93e87 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-php.mdx @@ -0,0 +1,88 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`$timings = new QueryTimings(); + +/** @var array $resultsWithTimings */ +$resultsWithTimings = $session->advanced()->documentQuery(Product::class) + ->timings($timings) + ->search("Name", "Syrup") + ->toList(); + +/** @var array $timingsMap */ +$timingsMap = $timings->getTimings(); +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from Studio's [Query view](../../../../studio/database/queries/query-view.mdx). + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`function timings(QueryTimings &$timings): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **&$timings** | `QueryTimings` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-python.mdx new file mode 100644 index 0000000000..ed2089f0f5 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/content/_query-timings-python.mdx @@ -0,0 +1,118 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a query, + you can request to get detailed stats of the time spent by RavenDB on each part of the query. + E.g. duration of search, loading documents, transforming results, total duration, etc. + +* By default, the timings stats are Not included in the query results, to avoid the measuring overhead. + +* **To include the query timings** in the query results: + add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query. + See examples below. + +* In this page: + * [Include timings in a query](../../../../client-api/session/querying/debugging/query-timings.mdx#include-timings-in-a-query) + * [View timings](../../../../client-api/session/querying/debugging/query-timings.mdx#view-timings) + * [Syntax](../../../../client-api/session/querying/debugging/query-timings.mdx#syntax) + * [Timings in a sharded database](../../../../client-api/session/querying/debugging/query-timings.mdx#timings-in-a-sharded-database) + + +## Include timings in a query + + + + +{`timings: Optional[QueryTimings] = None + +# Prepare a callback +def timings_callback(timings_from_server: QueryTimings): + timings = timings_from_server + +results = list( + session.advanced.document_query(object_type=Product) + # Call timings, provide a callback function that will be called with result timings + .timings(timings_callback) + # Define query criteria + # i.e. search for docs containing Syrup -or- Lager in their Name field + .search("Name", "Syrup Lager") + # Execute the query +) + +# Get total query duration: +# ========================= +total_query_duration = timings.duration_in_ms + +# Get specific parts duration: +# ============================ +timings_dictionary = timings.timings +optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms +lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms +`} + + + + +{`from "Products" +where search(Name, "Syrup") or search(Name, "Lager") +include timings() +`} + + + + + + +## View timings + +* The detailed timings can be viewed from the [Query view](../../../../studio/database/queries/query-view.mdx) in the Studio. + +* Running an RQL query with `include timings()` will show an additional **Timings Tab** + with a graphical representation of the time spent in each query part. + +![Figure 1. Include timings graphical results](../assets/include-timings.png) + + + +## Syntax + + + +{`def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|-------------|----------------|---------------| +| **timings_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. | + + + +{`class QueryTimings: + def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None): + self.duration_in_ms = duration_in_ms + self.timings = timings or \{\} +`} + + + +| `QueryTimings` | | | +|------------------|-------------------------------------|---------------------------------------------------| +| **duration_in_ms** | `int` | Total duration | +| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part | + + + +## Timings in a sharded database + +* In a sharded database, timings for each part are provided **per shard**. + +* Learn more in [timings in a sharded database](../../../../sharding/querying.mdx#timing-queries). + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/include-explanations.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/include-explanations.mdx index 75da2ffde5..43537fd201 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/include-explanations.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/include-explanations.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsJava from './_include-explanations-java.mdx'; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsPython from './_include-explanations-python.mdx'; -import IncludeExplanationsPhp from './_include-explanations-php.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsJava from './content/_include-explanations-java.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsPython from './content/_include-explanations-python.mdx'; +import IncludeExplanationsPhp from './content/_include-explanations-php.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/debugging/query-timings.mdx b/versioned_docs/version-7.1/client-api/session/querying/debugging/query-timings.mdx index 13181c0a6e..f2224411bf 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/debugging/query-timings.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/debugging/query-timings.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryTimingsCsharp from './_query-timings-csharp.mdx'; -import QueryTimingsJava from './_query-timings-java.mdx'; -import QueryTimingsPython from './_query-timings-python.mdx'; -import QueryTimingsPhp from './_query-timings-php.mdx'; -import QueryTimingsNodejs from './_query-timings-nodejs.mdx'; +import QueryTimingsCsharp from './content/_query-timings-csharp.mdx'; +import QueryTimingsJava from './content/_query-timings-java.mdx'; +import QueryTimingsPython from './content/_query-timings-python.mdx'; +import QueryTimingsPhp from './content/_query-timings-php.mdx'; +import QueryTimingsNodejs from './content/_query-timings-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-lucene-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-lucene-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_how-to-use-not-operator-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_how-to-use-not-operator-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_query-vs-document-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_query-vs-document-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/document-query/_what-is-document-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/document-query/content/_what-is-document-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-lucene.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-lucene.mdx index 56ea1dd656..0503e68233 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-lucene.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-lucene.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseLuceneCsharp from './_how-to-use-lucene-csharp.mdx'; -import HowToUseLuceneJava from './_how-to-use-lucene-java.mdx'; -import HowToUseLuceneNodejs from './_how-to-use-lucene-nodejs.mdx'; +import HowToUseLuceneCsharp from './content/_how-to-use-lucene-csharp.mdx'; +import HowToUseLuceneJava from './content/_how-to-use-lucene-java.mdx'; +import HowToUseLuceneNodejs from './content/_how-to-use-lucene-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx index 2e5a665c3e..5a2da9b67e 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/document-query/how-to-use-not-operator.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseNotOperatorCsharp from './_how-to-use-not-operator-csharp.mdx'; -import HowToUseNotOperatorJava from './_how-to-use-not-operator-java.mdx'; -import HowToUseNotOperatorNodejs from './_how-to-use-not-operator-nodejs.mdx'; +import HowToUseNotOperatorCsharp from './content/_how-to-use-not-operator-csharp.mdx'; +import HowToUseNotOperatorJava from './content/_how-to-use-not-operator-java.mdx'; +import HowToUseNotOperatorNodejs from './content/_how-to-use-not-operator-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/query-vs-document-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/query-vs-document-query.mdx index 6345cbee48..25143c2803 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/document-query/query-vs-document-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/document-query/query-vs-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryVsDocumentQueryCsharp from './_query-vs-document-query-csharp.mdx'; -import QueryVsDocumentQueryJava from './_query-vs-document-query-java.mdx'; -import QueryVsDocumentQueryPython from './_query-vs-document-query-python.mdx'; -import QueryVsDocumentQueryPhp from './_query-vs-document-query-php.mdx'; -import QueryVsDocumentQueryNodejs from './_query-vs-document-query-nodejs.mdx'; +import QueryVsDocumentQueryCsharp from './content/_query-vs-document-query-csharp.mdx'; +import QueryVsDocumentQueryJava from './content/_query-vs-document-query-java.mdx'; +import QueryVsDocumentQueryPython from './content/_query-vs-document-query-python.mdx'; +import QueryVsDocumentQueryPhp from './content/_query-vs-document-query-php.mdx'; +import QueryVsDocumentQueryNodejs from './content/_query-vs-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/document-query/what-is-document-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/document-query/what-is-document-query.mdx index 02da2bf41c..1c9109a5fa 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/document-query/what-is-document-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/document-query/what-is-document-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsDocumentQueryCsharp from './_what-is-document-query-csharp.mdx'; -import WhatIsDocumentQueryJava from './_what-is-document-query-java.mdx'; -import WhatIsDocumentQueryPython from './_what-is-document-query-python.mdx'; -import WhatIsDocumentQueryPhp from './_what-is-document-query-php.mdx'; -import WhatIsDocumentQueryNodejs from './_what-is-document-query-nodejs.mdx'; +import WhatIsDocumentQueryCsharp from './content/_what-is-document-query-csharp.mdx'; +import WhatIsDocumentQueryJava from './content/_what-is-document-query-java.mdx'; +import WhatIsDocumentQueryPython from './content/_what-is-document-query-python.mdx'; +import WhatIsDocumentQueryPhp from './content/_what-is-document-query-php.mdx'; +import WhatIsDocumentQueryNodejs from './content/_what-is-document-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-count-query-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-count-query-results.mdx index 47dfadf078..dd21d200a7 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-count-query-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-count-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCountQueryResultsCsharp from './_how-to-count-query-results-csharp.mdx'; -import HowToCountQueryResultsPython from './_how-to-count-query-results-python.mdx'; -import HowToCountQueryResultsPhp from './_how-to-count-query-results-php.mdx'; -import HowToCountQueryResultsNodejs from './_how-to-count-query-results-nodejs.mdx'; +import HowToCountQueryResultsCsharp from './content/_how-to-count-query-results-csharp.mdx'; +import HowToCountQueryResultsPython from './content/_how-to-count-query-results-python.mdx'; +import HowToCountQueryResultsPhp from './content/_how-to-count-query-results-php.mdx'; +import HowToCountQueryResultsNodejs from './content/_how-to-count-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-customize-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-customize-query.mdx index c96c393d52..68376d3b67 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-customize-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-customize-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToCustomizeQueryCsharp from './_how-to-customize-query-csharp.mdx'; -import HowToCustomizeQueryJava from './_how-to-customize-query-java.mdx'; -import HowToCustomizeQueryPython from './_how-to-customize-query-python.mdx'; -import HowToCustomizeQueryPhp from './_how-to-customize-query-php.mdx'; -import HowToCustomizeQueryNodejs from './_how-to-customize-query-nodejs.mdx'; +import HowToCustomizeQueryCsharp from './content/_how-to-customize-query-csharp.mdx'; +import HowToCustomizeQueryJava from './content/_how-to-customize-query-java.mdx'; +import HowToCustomizeQueryPython from './content/_how-to-customize-query-python.mdx'; +import HowToCustomizeQueryPhp from './content/_how-to-customize-query-php.mdx'; +import HowToCustomizeQueryNodejs from './content/_how-to-customize-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-field.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-field.mdx index 4bd71ae319..cc8edfbdef 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-field.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-field.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByFieldCsharp from './_how-to-filter-by-field-csharp.mdx'; -import HowToFilterByFieldJava from './_how-to-filter-by-field-java.mdx'; -import HowToFilterByFieldPython from './_how-to-filter-by-field-python.mdx'; -import HowToFilterByFieldPhp from './_how-to-filter-by-field-php.mdx'; -import HowToFilterByFieldNodejs from './_how-to-filter-by-field-nodejs.mdx'; +import HowToFilterByFieldCsharp from './content/_how-to-filter-by-field-csharp.mdx'; +import HowToFilterByFieldJava from './content/_how-to-filter-by-field-java.mdx'; +import HowToFilterByFieldPython from './content/_how-to-filter-by-field-python.mdx'; +import HowToFilterByFieldPhp from './content/_how-to-filter-by-field-php.mdx'; +import HowToFilterByFieldNodejs from './content/_how-to-filter-by-field-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx index 5e6fe8863b..f840df805f 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-filter-by-non-existing-field.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToFilterByNonExistingFieldCsharp from './_how-to-filter-by-non-existing-field-csharp.mdx'; -import HowToFilterByNonExistingFieldPython from './_how-to-filter-by-non-existing-field-python.mdx'; -import HowToFilterByNonExistingFieldPhp from './_how-to-filter-by-non-existing-field-php.mdx'; -import HowToFilterByNonExistingFieldNodejs from './_how-to-filter-by-non-existing-field-nodejs.mdx'; +import HowToFilterByNonExistingFieldCsharp from './content/_how-to-filter-by-non-existing-field-csharp.mdx'; +import HowToFilterByNonExistingFieldPython from './content/_how-to-filter-by-non-existing-field-python.mdx'; +import HowToFilterByNonExistingFieldPhp from './content/_how-to-filter-by-non-existing-field-php.mdx'; +import HowToFilterByNonExistingFieldNodejs from './content/_how-to-filter-by-non-existing-field-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-get-query-statistics.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-get-query-statistics.mdx index 57caf2e000..0f1849b072 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-get-query-statistics.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-get-query-statistics.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToGetQueryStatisticsCsharp from './_how-to-get-query-statistics-csharp.mdx'; -import HowToGetQueryStatisticsJava from './_how-to-get-query-statistics-java.mdx'; -import HowToGetQueryStatisticsPython from './_how-to-get-query-statistics-python.mdx'; -import HowToGetQueryStatisticsPhp from './_how-to-get-query-statistics-php.mdx'; -import HowToGetQueryStatisticsNodejs from './_how-to-get-query-statistics-nodejs.mdx'; +import HowToGetQueryStatisticsCsharp from './content/_how-to-get-query-statistics-csharp.mdx'; +import HowToGetQueryStatisticsJava from './content/_how-to-get-query-statistics-java.mdx'; +import HowToGetQueryStatisticsPython from './content/_how-to-get-query-statistics-python.mdx'; +import HowToGetQueryStatisticsPhp from './content/_how-to-get-query-statistics-php.mdx'; +import HowToGetQueryStatisticsNodejs from './content/_how-to-get-query-statistics-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-make-a-spatial-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-make-a-spatial-query.mdx index 21003aa9f2..277c01064a 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-make-a-spatial-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-make-a-spatial-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToMakeASpatialQueryCsharp from './_how-to-make-a-spatial-query-csharp.mdx'; -import HowToMakeASpatialQueryJava from './_how-to-make-a-spatial-query-java.mdx'; -import HowToMakeASpatialQueryPython from './_how-to-make-a-spatial-query-python.mdx'; -import HowToMakeASpatialQueryNodejs from './_how-to-make-a-spatial-query-nodejs.mdx'; +import HowToMakeASpatialQueryCsharp from './content/_how-to-make-a-spatial-query-csharp.mdx'; +import HowToMakeASpatialQueryJava from './content/_how-to-make-a-spatial-query-java.mdx'; +import HowToMakeASpatialQueryPython from './content/_how-to-make-a-spatial-query-python.mdx'; +import HowToMakeASpatialQueryNodejs from './content/_how-to-make-a-spatial-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx index 4d1a061f61..6eb27f7e47 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-a-faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformAFacetedSearchCsharp from './_how-to-perform-a-faceted-search-csharp.mdx'; -import HowToPerformAFacetedSearchJava from './_how-to-perform-a-faceted-search-java.mdx'; -import HowToPerformAFacetedSearchPython from './_how-to-perform-a-faceted-search-python.mdx'; -import HowToPerformAFacetedSearchPhp from './_how-to-perform-a-faceted-search-php.mdx'; -import HowToPerformAFacetedSearchNodejs from './_how-to-perform-a-faceted-search-nodejs.mdx'; +import HowToPerformAFacetedSearchCsharp from './content/_how-to-perform-a-faceted-search-csharp.mdx'; +import HowToPerformAFacetedSearchJava from './content/_how-to-perform-a-faceted-search-java.mdx'; +import HowToPerformAFacetedSearchPython from './content/_how-to-perform-a-faceted-search-python.mdx'; +import HowToPerformAFacetedSearchPhp from './content/_how-to-perform-a-faceted-search-php.mdx'; +import HowToPerformAFacetedSearchNodejs from './content/_how-to-perform-a-faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-group-by-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-group-by-query.mdx index 8f5783600d..b8f5cb357b 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-group-by-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-group-by-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformGroupByQueryCsharp from './_how-to-perform-group-by-query-csharp.mdx'; -import HowToPerformGroupByQueryJava from './_how-to-perform-group-by-query-java.mdx'; -import HowToPerformGroupByQueryPython from './_how-to-perform-group-by-query-python.mdx'; -import HowToPerformGroupByQueryPhp from './_how-to-perform-group-by-query-php.mdx'; -import HowToPerformGroupByQueryNodejs from './_how-to-perform-group-by-query-nodejs.mdx'; +import HowToPerformGroupByQueryCsharp from './content/_how-to-perform-group-by-query-csharp.mdx'; +import HowToPerformGroupByQueryJava from './content/_how-to-perform-group-by-query-java.mdx'; +import HowToPerformGroupByQueryPython from './content/_how-to-perform-group-by-query-python.mdx'; +import HowToPerformGroupByQueryPhp from './content/_how-to-perform-group-by-query-php.mdx'; +import HowToPerformGroupByQueryNodejs from './content/_how-to-perform-group-by-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-queries-lazily.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-queries-lazily.mdx index 17e2bf7b5f..53f8c43bd0 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-queries-lazily.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-perform-queries-lazily.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToPerformQueriesLazilyCsharp from './_how-to-perform-queries-lazily-csharp.mdx'; -import HowToPerformQueriesLazilyJava from './_how-to-perform-queries-lazily-java.mdx'; -import HowToPerformQueriesLazilyPython from './_how-to-perform-queries-lazily-python.mdx'; -import HowToPerformQueriesLazilyPhp from './_how-to-perform-queries-lazily-php.mdx'; -import HowToPerformQueriesLazilyNodejs from './_how-to-perform-queries-lazily-nodejs.mdx'; +import HowToPerformQueriesLazilyCsharp from './content/_how-to-perform-queries-lazily-csharp.mdx'; +import HowToPerformQueriesLazilyJava from './content/_how-to-perform-queries-lazily-java.mdx'; +import HowToPerformQueriesLazilyPython from './content/_how-to-perform-queries-lazily-python.mdx'; +import HowToPerformQueriesLazilyPhp from './content/_how-to-perform-queries-lazily-php.mdx'; +import HowToPerformQueriesLazilyNodejs from './content/_how-to-perform-queries-lazily-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-project-query-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-project-query-results.mdx index 005a01c964..505ff9b85d 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-project-query-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-project-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToProjectQueryResultsCsharp from './_how-to-project-query-results-csharp.mdx'; -import HowToProjectQueryResultsJava from './_how-to-project-query-results-java.mdx'; -import HowToProjectQueryResultsPython from './_how-to-project-query-results-python.mdx'; -import HowToProjectQueryResultsPhp from './_how-to-project-query-results-php.mdx'; -import HowToProjectQueryResultsNodejs from './_how-to-project-query-results-nodejs.mdx'; +import HowToProjectQueryResultsCsharp from './content/_how-to-project-query-results-csharp.mdx'; +import HowToProjectQueryResultsJava from './content/_how-to-project-query-results-java.mdx'; +import HowToProjectQueryResultsPython from './content/_how-to-project-query-results-python.mdx'; +import HowToProjectQueryResultsPhp from './content/_how-to-project-query-results-php.mdx'; +import HowToProjectQueryResultsNodejs from './content/_how-to-project-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-query.mdx index 49e3d72b25..59d527a3b2 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToQueryCsharp from './_how-to-query-csharp.mdx'; -import HowToQueryPython from './_how-to-query-python.mdx'; -import HowToQueryPhp from './_how-to-query-php.mdx'; -import HowToQueryNodejs from './_how-to-query-nodejs.mdx'; +import HowToQueryCsharp from './content/_how-to-query-csharp.mdx'; +import HowToQueryPython from './content/_how-to-query-python.mdx'; +import HowToQueryPhp from './content/_how-to-query-php.mdx'; +import HowToQueryNodejs from './content/_how-to-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-stream-query-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-stream-query-results.mdx index 7533c20640..b4969b1cf9 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-stream-query-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-stream-query-results.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToStreamQueryResultsCsharp from './_how-to-stream-query-results-csharp.mdx'; -import HowToStreamQueryResultsJava from './_how-to-stream-query-results-java.mdx'; -import HowToStreamQueryResultsNodejs from './_how-to-stream-query-results-nodejs.mdx'; +import HowToStreamQueryResultsCsharp from './content/_how-to-stream-query-results-csharp.mdx'; +import HowToStreamQueryResultsJava from './content/_how-to-stream-query-results-java.mdx'; +import HowToStreamQueryResultsNodejs from './content/_how-to-stream-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-use-intersect.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-use-intersect.mdx index 3538aa138f..e1be6e76e2 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-use-intersect.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-use-intersect.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseIntersectCsharp from './_how-to-use-intersect-csharp.mdx'; -import HowToUseIntersectJava from './_how-to-use-intersect-java.mdx'; -import HowToUseIntersectPython from './_how-to-use-intersect-python.mdx'; -import HowToUseIntersectPhp from './_how-to-use-intersect-php.mdx'; -import HowToUseIntersectNodejs from './_how-to-use-intersect-nodejs.mdx'; +import HowToUseIntersectCsharp from './content/_how-to-use-intersect-csharp.mdx'; +import HowToUseIntersectJava from './content/_how-to-use-intersect-java.mdx'; +import HowToUseIntersectPython from './content/_how-to-use-intersect-python.mdx'; +import HowToUseIntersectPhp from './content/_how-to-use-intersect-php.mdx'; +import HowToUseIntersectNodejs from './content/_how-to-use-intersect-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-use-morelikethis.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-use-morelikethis.mdx index cc14b20e2d..49d6979903 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-use-morelikethis.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-use-morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToUseMorelikethisCsharp from './_how-to-use-morelikethis-csharp.mdx'; -import HowToUseMorelikethisJava from './_how-to-use-morelikethis-java.mdx'; -import HowToUseMorelikethisPython from './_how-to-use-morelikethis-python.mdx'; -import HowToUseMorelikethisPhp from './_how-to-use-morelikethis-php.mdx'; -import HowToUseMorelikethisNodejs from './_how-to-use-morelikethis-nodejs.mdx'; +import HowToUseMorelikethisCsharp from './content/_how-to-use-morelikethis-csharp.mdx'; +import HowToUseMorelikethisJava from './content/_how-to-use-morelikethis-java.mdx'; +import HowToUseMorelikethisPython from './content/_how-to-use-morelikethis-python.mdx'; +import HowToUseMorelikethisPhp from './content/_how-to-use-morelikethis-php.mdx'; +import HowToUseMorelikethisNodejs from './content/_how-to-use-morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/how-to-work-with-suggestions.mdx b/versioned_docs/version-7.1/client-api/session/querying/how-to-work-with-suggestions.mdx index a9875f6cd7..08dff38eb1 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/how-to-work-with-suggestions.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/how-to-work-with-suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HowToWorkWithSuggestionsJava from './_how-to-work-with-suggestions-java.mdx'; -import HowToWorkWithSuggestionsCsharp from './_how-to-work-with-suggestions-csharp.mdx'; -import HowToWorkWithSuggestionsPython from './_how-to-work-with-suggestions-python.mdx'; -import HowToWorkWithSuggestionsPhp from './_how-to-work-with-suggestions-php.mdx'; -import HowToWorkWithSuggestionsNodejs from './_how-to-work-with-suggestions-nodejs.mdx'; +import HowToWorkWithSuggestionsJava from './content/_how-to-work-with-suggestions-java.mdx'; +import HowToWorkWithSuggestionsCsharp from './content/_how-to-work-with-suggestions-csharp.mdx'; +import HowToWorkWithSuggestionsPython from './content/_how-to-work-with-suggestions-python.mdx'; +import HowToWorkWithSuggestionsPhp from './content/_how-to-work-with-suggestions-php.mdx'; +import HowToWorkWithSuggestionsNodejs from './content/_how-to-work-with-suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/sort-query-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/sort-query-results.mdx index a34e918743..26b8cb85a3 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/sort-query-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/sort-query-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortQueryResultsCsharp from './_sort-query-results-csharp.mdx'; -import SortQueryResultsPython from './_sort-query-results-python.mdx'; -import SortQueryResultsPhp from './_sort-query-results-php.mdx'; -import SortQueryResultsNodejs from './_sort-query-results-nodejs.mdx'; +import SortQueryResultsCsharp from './content/_sort-query-results-csharp.mdx'; +import SortQueryResultsPython from './content/_sort-query-results-python.mdx'; +import SortQueryResultsPhp from './content/_sort-query-results-php.mdx'; +import SortQueryResultsNodejs from './content/_sort-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx deleted file mode 100644 index f310662934..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-csharp.mdx +++ /dev/null @@ -1,462 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - // Make a dynamic query on 'Employees' collection - .Query() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the query - .ToListAsync(); -`} - - - - -{`// Make a full-text search dynamic DocumentQuery: -// ============================================== -List employeesResults = session.Advanced - // Make a dynamic documentQuery on 'Employees' collection - .DocumentQuery() - // Search for documents containing the term 'sales' in their 'Notes' field - .Search(x => x.Notes, "sales") - // Request to highlight the searched term by calling 'Highlight' - .Highlight( - x => x.Notes, // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - out Highlightings salesHighlights) // An out param for getting the highlighted text fragments - // Execute the documentQuery - .ToList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -StringBuilder builder = new StringBuilder().AppendLine("
    "); - -foreach (var employee in employeesResults) -\{ - // Call 'GetFragments' to get all fragments for the specified employee Id - string[] fragments = salesHighlights.GetFragments(employee.Id); - foreach (var fragment in fragments) - \{ - builder.AppendLine( - $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); - \} -\} - -string fragmentsHtml = builder.AppendLine("
").ToString(); - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // the first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = session - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToList(); -`} - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -HighlightingOptions tagsToUse = new HighlightingOptions -{ - // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - // The first term searched for will be wrapped with '+++' - // the second term searched for will be wrapped with '<<<' & '>>>' - PreTags = new[] { "+++", "<<<" }, - PostTags = new[] { "+++", ">>>" } -}; - -// Make a full-text search dynamic query: -// ====================================== -List employeesResults = await asyncSession - .Query() - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .Search(x => x.Notes, "sales") - .Search(x => x.Title, "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) - .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) - .ToListAsync(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = session - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToList(); -`} - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -var employeesProjectedResults = await asyncSession - .Query() - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .Search(x => x.Notes, "manager german") - // Request to highlight the searched terms from the 'Notes' field - .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) - // Define the projection - .Select(x => new - { - // These fields will be returned instead of the whole document - // Note: it is Not mandatory to return the field in which we search for the highlights - Name = $"{x.FirstName} {x.LastName}", - x.Title - }) - .ToListAsync(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - string fieldName, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - out Highlightings highlightings); - -IRavenQueryable Highlight( - Expression> path, - int fragmentLength, - int fragmentCount, - HighlightingOptions options, - out Highlightings highlightings); -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| -| **fieldName** | string | Name of the field that contains the searched terms to highlight. | -| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | -| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | -| **fragmentCount** | int | Maximum number of text fragments that will be returned. | -| **options** | `HighlightingOptions` | Customizing options. | -| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | - -
- -**Highlighting options**: - - - -{`public string GroupKey \{ get; set; \} -public string[] PreTags \{ get; set; \} -public string[] PostTags \{ get; set; \} -`} - - - -| Option | Type | Description | -|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`public string FieldName \{ get; \} -public IEnumerable ResultIndents; -`} - - - -| Property | Type | Description | -|-------------------|----------------------|------------------------------------------------------------------| -| **FieldName** | string | Name of the field that contains the searched terms to highlight. | -| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | - - - -{`public string[] GetFragments(string key); -`} - - - -| Method | Description | -|------------------|-------------------------------------------------------------------------------------------------------| -| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx deleted file mode 100644 index 2941391736..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-nodejs.mdx +++ /dev/null @@ -1,339 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a __list of text fragments that highlight the searched terms__. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a __dynamic-query__. - For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -// Define a param that will get the highlighted text fragments -let salesHighlights; - -const employeesResults = await session - // Make a dynamic query on 'Employees' collection - .query({ collection: "Employees" }) - // Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight' - .highlight({ - fieldName: 'Notes', // The document-field name in which we search - fragmentLength: 35, // Max length of each text fragment - fragmentCount: 4 }, // Max number of fragments to return per document - x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled - // with the highlighted text fragments when query returns. - // Execute the query - .all(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -let fragmentsHtml = "
    "; - -employeesResults.forEach((employee) => \{ - // Call 'getFragments' to get all fragments for the specified employee id - let fragments = salesHighlights.getFragments(employee.id); - - fragments.forEach((fragment) => \{ - fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; - \}); -\}); - -fragmentsHtml += "
"; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. __Auto-Index__ - This is the auto-index that was created by the server to serve the dynamic-query. - -2. __Results tab__ - The results tab contains the resulting __documents__ that match the provided RQL query. - -3. __Highlight tab__ - The highlight tab shows the resulting __fragments__ that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be __customized__ to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= -const tagsToUse = { - preTags: ["+++", "<<<"], - postTags: ["+++", ">>>"] -}; - -// Make a full-text search dynamic query: -// ====================================== -let salesHighlights; -let managerHighlights; - -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - // Call 'highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { salesHighlights = x; }) - .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, - x => { managerHighlights = x; }) - .all(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== - -// Define a param that will get the highlighted text fragments -let termsHighlights; - -// Define the class for the projected results -class Result { - constructor () { - this.Name = null; - this.Title = null; - } -} - -// Make a dynamic query on 'Employees' collection -const employeesResults = await session - .query({ collection: "Employees" }) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - .search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, - x => { termsHighlights = x; }) - // Define the projection - .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), - Result) - .all(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`highlight(parameters, hightlightingsCallback); -`} - - - -| Parameter | Type | Description | -|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | -| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | - -
- -__The Highlighting parameters:__ - -| Parameter | Type | Description | -|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | -| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | -| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | -| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -__The Highlightings object__: - - - -{`class Highlightings \{ - // Name of the field that contains the searched terms to highlight. - get fieldName(); - // The resulting keys (document IDs, or the map-reduce keys) - get resultIndents(); - // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key - getFragments(key); -\} -`} - - - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-php.mdx deleted file mode 100644 index b8325ec0cf..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-php.mdx +++ /dev/null @@ -1,359 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`// Make a full-text search dynamic query: -// ====================================== - -$highlightings = new Highlightings(); - -/** @var array $employeesResults */ -$employeesResults = $session - // Make a dynamic query on 'Employees' collection - ->query(Employee::class) - // Search for documents containing the term 'sales' in their 'Notes' field - ->search("Notes", "sales") - // Request to highlight the searched term by calling 'highlight()' - ->highlight( - "Notes", // The document-field name in which we search - 35, // Max length of each text fragment - 4, // Max number of fragments to return per document - null, // Put null to use default options - $highlightings) // An out param for getting the highlighted text fragments - - // Execute the query - ->toList(); -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`// Process results: -// ================ - -// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. - -$builder = '
    '; - -/** @var SearchItem $employee */ -foreach ($employeesResults as $employee) \{ - // Call 'GetFragments' to get all fragments for the specified employee Id - $fragments = $highlightings->getFragments($employee->getId()); - foreach ($fragments as $fragment) \{ - $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; - \} -\} - -$builder .= '
'; -$fragmentsHtml = $builder; - -// The resulting fragmentsHtml: -// ============================ - -//
    -//
  • Doc: employees/2-A Fragment: company as a sales
    • -//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -//
  • Doc: employees/5-A Fragment: Sales Management."
    • -//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -//
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`// Define customized tags to use for highlighting the searched terms -// ================================================================= - -$salesHighlights = new Highlightings(); -$managerHighlights = new Highlightings(); - -$tagsToUse = new HighlightingOptions(); -// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: -// the first term searched for will be wrapped with '+++' -// the second term searched for will be wrapped with '<<<' & '>>>' -$tagsToUse->setPreTags(["+++", "<<<"]); -$tagsToUse->setPostTags(["+++", ">>>"]); - -// Make a full-text search dynamic query: -// ====================================== -$employeesResults = $session - ->query(Employee::class) - // Search for: - // * documents containing the term 'sales' in their 'Notes' field - // * OR for documents containing the term 'manager' in their 'Title' field - ->search("Notes", "sales") - ->search("Title", "manager") - // Call 'Highlight' for each field searched - // Pass 'tagsToUse' to OVERRIDE the default tags used - ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) - ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) - ->toList(); -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`// The resulting salesHighlights fragments: -// ======================================== - -// "for the +++Sales+++ Professional." -// "hired as a +++sales+++ associate in" -// "company as a +++sales+++" -// "company as a +++sales+++ representativ" - -// The resulting managerHighlights fragments: -// ========================================== - -// "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`// Make a full-text search dynamic query & project results: -// ======================================================== -$termsHighlights = new Highlightings(); - -/** @var array $employeesProjectedResults */ -$employeesProjectedResults = $session - ->query(Employee::class) - // Search for documents containing 'sales' or 'german' in their 'Notes' field - ->search("Notes", "manager german") - // Request to highlight the searched terms from the 'Notes' field - ->highlight("Notes", 35, 2, null, $termsHighlights) - // Define the projection - ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) - ->toList(); -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`// The resulting fragments from termsHighlights: -// ============================================= - -// "to sales manager in March" -// "and reads German. He joined" -// "to sales manager in January" -// "in French and German." - -// NOTE: each search term is wrapped with a different color -// 'manager' is wrapped with yellow -// 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`function highlight( - ?string $fieldName, - int $fragmentLength, - int $fragmentCount, - ?HighlightingOptions $options, - Highlightings &$highlightings -): DocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | -| **$options** | `?HighlightingOptions ` | Customizing options | -| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | - -
- -**Highlighting options**: - - - -{`private ?string $groupKey; -private ?StringArray $preTags = null; -private ?StringArray $postTags = null; - -// getters and setters -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`private ?string $fieldName = null; -public function getResultIndents(): array; -`} - - - -| Property | Type | Description | -|--------------------|------------|-------------| -| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | -| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`public function getFragments(?string $key): array; -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|-------------| -| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-python.mdx deleted file mode 100644 index 9668e3146a..0000000000 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-python.mdx +++ /dev/null @@ -1,370 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), - in addition to retrieving documents that contain the searched terms in the results, - you can also request to get a **list of text fragments that highlight the searched terms**. - -* The highlighted terms can enhance user experience when searching for documents with specific content. - -* This article shows highlighting search results when making a **dynamic-query**. - For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). -* In this page: - * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) - * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) - * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) - * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) - * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) - * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) - - -## Highlight - basic example - - - - -{`# Make a full-text search dynamic query: -# ====================================== - -# Define a callback that takes highlightings as an argument -sales_highlightings: Optional[Highlightings] = None - -def _sales_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - sales_highlightings = highlightings - -employees_result = list( # Execute the query inside the parenthesis - session - # Make a query on 'Employees' collection - .query(object_type=Employee) - # Search for documents containing the term 'sales' in their 'Notes' field - .search("Notes", "sales") - # Request to highlight the searched term by calling 'Highlight' - .highlight( - "Notes", # The document-field name in which we search - 35, # Max length of each text fragment - 4, # Max number of fragments to return per document - _sales_highlights, # An out param for getting the highlighted text fragments - ) -) -`} - - - - -{`from "Employees" -where search(Notes, "sales") -include highlight(Notes, 35, 4) -`} - - - - - - -{`# Process results: -# ================ - -# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. -# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. - -builder = ["
    ", \{os.linesep\}] -for employee in employees_result: - # Call 'get_fragments' to get all fragments for the specified employee Id - fragments = sales_highlightings.get_fragments(employee.Id) - for fragment in fragments: - builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") - -fragments_html = builder.append(f"\{os.linesep\}
") - -# The resulting fragments_html: -# ============================ - -#
    -#
  • Doc: employees/2-A Fragment: company as a sales
    • -#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • -#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • -#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • -#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • -#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • -#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • -#
  • Doc: employees/5-A Fragment: Sales Management."
    • -#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • -#
-`} - - - - - -#### Highlight tags - -* By default, the highlighted term is wrapped with the following html: - `term` - -* When requesting to highlight multiple terms, - the background color returned for each different term will be in the following order: - - - <span style="border-left: 10px solid yellow"> </span>yellow, - - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, - - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, - - <span style="border-left: 10px solid magenta"> </span>magenta, - - <span style="border-left: 10px solid palegreen"> </span>palegreen, - - <span style="border-left: 10px solid coral"> </span>coral, - - <span style="border-left: 10px solid wheat"> </span>wheat, - - <span style="border-left: 10px solid khaki"> </span>khaki, - - <span style="border-left: 10px solid lime"> </span>lime, - - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, - - <span style="border-left: 10px solid deeppink"> </span>deeppink, - - <span style="border-left: 10px solid salmon"> </span>salmon, - - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, - - <span style="border-left: 10px solid violet"> </span>violet, - - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, - - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, - - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, - - <span style="border-left: 10px solid springgreen"> </span>springgreen, - - <span style="border-left: 10px solid turquoise"> </span>turquoise, - - <span style="border-left: 10px solid powderblue"> </span>powderblue - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. - - - - - -#### Highlight results in Studio - -![Figure 1. Fragments results](./assets/fragmentsResults.png) - -1. **Auto-Index** - This is the auto-index that was created by the server to serve the dynamic-query. - -2. **Results tab** - The results tab contains the resulting **documents** that match the provided RQL query. - -3. **Highlight tab** - The highlight tab shows the resulting **fragments** that were included in the query result. - - - - - -## Highlight - customize tags - -* The html tags that wrap the highlighted terms can be **customized** to any other tags. - - - - -{`# Define customized tags to use for highlighting the searched terms -# ================================================================= -tags_to_use = HighlightingOptions( - # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: - # the first term searched for will be wrapped with '+++' - # the second term searched for will be wrapped with '<<<' & '>>>' - pre_tags=["+++", "<<<"], - post_tags=["+++", ">>>"], -) - -# Define a callback that takes highlightings as an argument -manager_highlightings: Optional[Highlightings] = None - -def _manager_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - manager_highlightings = highlightings - -# Make a full-text search dynamic query: -# ====================================== -employees_result = list( - session.query(object_type=Employee) - # Search for: - # * documents containing the term 'sales' in their 'Notes' field - # * OR for documents containing the term 'manager' in their 'Title' field - .search("Notes", "sales") - .search("Title", "manager") - # Call 'Highlight' for each field searched - # Pass 'tagsToUse' to OVERRIDE the default tags used - .highlight("Notes", 35, 1, _sales_highlights) - .highlight("Title", 35, 1, tags_to_use, _manager_highlights) -) -`} - - - - -{`from "Employees" -where (search(Notes, "sales") or search(Title, "manager")) -include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) -{ -"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, -"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} -} -`} - - - - - - -{`# The resulting salesHighlights fragments: -# ======================================== -# -# "for the +++Sales+++ Professional." -# "hired as a +++sales+++ associate in" -# "company as a +++sales+++" -# "company as a +++sales+++ representative" -# -# The resulting managerHighlights fragments: -# ========================================== -# -# "Sales <<>>" -`} - - - - - -## Highlight - projected results - -* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). - - - - -{`# Make a full-text search dynamic query & project results: -# ======================================================== - -# Define a callback that takes highlightings as an argument -terms_highlightings: Optional[Highlightings] = None - -def _terms_highlights(highlightings: Highlightings): - # You may use the results (highlightings) here in any way desired - terms_highlightings = highlightings - -employees_projected = list( - session.query(object_type=Employee) - .search("Notes", "manager german") - .highlight("Notes", 35, 2, _terms_highlights) - .select_fields_query_data( - QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), - ) -) - -`} - - - - -{`from "Employees" as x -where search(x.Notes, "manager german") -select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } -include highlight(Notes, 35, 2) -`} - - - - - - -{`# The resulting fragments from termsHighlights: -# ============================================= -# -# "to sales manager in March" -# "and reads German. He joined" -# "to sales manager in January" -# "in French and German." -# -# NOTE: each search term is wrapped with a different color -# 'manager' is wrapped with yellow -# 'german' is wrapped with lawngreen -`} - - - - - -## Syntax - - - -{`def highlight( - self, - field_name: str, - fragment_length: int, - fragment_count: int, - highlightings_callback: Callable[[Highlightings], None], - options: Optional[HighlightingOptions] = None, -) -> DocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|--------------------|-------------------------------|-------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | -| **fragment_count** | `int` | Maximum number of text fragments that will be returned | -| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | -| **options** (Optional) | `HighlightingOptions ` | Customizing options | - -
- -**Highlighting options**: - - - -{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): - self.group_key = group_key - self.pre_tags = pre_tags - self.post_tags = post_tags -`} - - - -| Option | Type | Description | -|--------------|-----------|--------------| -| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | -| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | -| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | - -
- -**Highlightings object**: - - - -{`def __init__(self, field_name: str): - self.field_name = field_name - ... - -@property -def result_indents(self) -> Set[str]: ... -`} - - - -| Property | Type | Description | -|--------------------|------------|-----------------------------------------------------------------| -| **field_name** | `str` | Name of the field that contains the searched terms to highlight | -| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | - - - -{`def get_fragments(self, key: str) -> List[str]: ... -`} - - - -| Method | Return Type | Description | -|-------------------|-------------|------------------------------------------------------------------------------------------------------| -| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | - - - - diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/boost-search-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/boost-search-results.mdx index 328efebf4b..a5e0917e9a 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/boost-search-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/boost-search-results.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostSearchResultsCsharp from './_boost-search-results-csharp.mdx'; -import BoostSearchResultsPython from './_boost-search-results-python.mdx'; -import BoostSearchResultsPhp from './_boost-search-results-php.mdx'; -import BoostSearchResultsNodejs from './_boost-search-results-nodejs.mdx'; +import BoostSearchResultsCsharp from './content/_boost-search-results-csharp.mdx'; +import BoostSearchResultsPython from './content/_boost-search-results-python.mdx'; +import BoostSearchResultsPhp from './content/_boost-search-results-php.mdx'; +import BoostSearchResultsNodejs from './content/_boost-search-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_boost-search-results-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_boost-search-results-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_ends-with-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_ends-with-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_exact-match-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_exact-match-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_full-text-search-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_full-text-search-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_fuzzy-search-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_fuzzy-search-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx new file mode 100644 index 0000000000..a220cdb5de --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-csharp.mdx @@ -0,0 +1,462 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + // Make a dynamic query on 'Employees' collection + .Query() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the query + .ToListAsync(); +`} + + + + +{`// Make a full-text search dynamic DocumentQuery: +// ============================================== +List employeesResults = session.Advanced + // Make a dynamic documentQuery on 'Employees' collection + .DocumentQuery() + // Search for documents containing the term 'sales' in their 'Notes' field + .Search(x => x.Notes, "sales") + // Request to highlight the searched term by calling 'Highlight' + .Highlight( + x => x.Notes, // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + out Highlightings salesHighlights) // An out param for getting the highlighted text fragments + // Execute the documentQuery + .ToList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +StringBuilder builder = new StringBuilder().AppendLine("
    "); + +foreach (var employee in employeesResults) +\{ + // Call 'GetFragments' to get all fragments for the specified employee Id + string[] fragments = salesHighlights.GetFragments(employee.Id); + foreach (var fragment in fragments) + \{ + builder.AppendLine( + $"
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • "); + \} +\} + +string fragmentsHtml = builder.AppendLine("
").ToString(); + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // the first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = session + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToList(); +`} + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +HighlightingOptions tagsToUse = new HighlightingOptions +{ + // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + // The first term searched for will be wrapped with '+++' + // the second term searched for will be wrapped with '<<<' & '>>>' + PreTags = new[] { "+++", "<<<" }, + PostTags = new[] { "+++", ">>>" } +}; + +// Make a full-text search dynamic query: +// ====================================== +List employeesResults = await asyncSession + .Query() + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .Search(x => x.Notes, "sales") + .Search(x => x.Title, "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights) + .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights) + .ToListAsync(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = session + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToList(); +`} + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +var employeesProjectedResults = await asyncSession + .Query() + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .Search(x => x.Notes, "manager german") + // Request to highlight the searched terms from the 'Notes' field + .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights) + // Define the projection + .Select(x => new + { + // These fields will be returned instead of the whole document + // Note: it is Not mandatory to return the field in which we search for the highlights + Name = $"{x.FirstName} {x.LastName}", + x.Title + }) + .ToListAsync(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + string fieldName, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + out Highlightings highlightings); + +IRavenQueryable Highlight( + Expression> path, + int fragmentLength, + int fragmentCount, + HighlightingOptions options, + out Highlightings highlightings); +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------------------------------------------------------------| +| **fieldName** | string | Name of the field that contains the searched terms to highlight. | +| **path** | `Expression>` | Path to the field that contains the searched terms to highlight. | +| **fragmentLength** | int | Maximum length of a text fragment. Must be `>= 18`. | +| **fragmentCount** | int | Maximum number of text fragments that will be returned. | +| **options** | `HighlightingOptions` | Customizing options. | +| **highlightings** | `Highlightings` | An 'out' param that will contain the highlighted text fragments for each returned result. | + +
+ +**Highlighting options**: + + + +{`public string GroupKey \{ get; set; \} +public string[] PreTags \{ get; set; \} +public string[] PostTags \{ get; set; \} +`} + + + +| Option | Type | Description | +|--------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **GroupKey** | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **PreTags** | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **PostTags** | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`public string FieldName \{ get; \} +public IEnumerable ResultIndents; +`} + + + +| Property | Type | Description | +|-------------------|----------------------|------------------------------------------------------------------| +| **FieldName** | string | Name of the field that contains the searched terms to highlight. | +| **ResultIndents** | `IEumerable` | The resulting keys (document IDs, or the map-reduce keys). | + + + +{`public string[] GetFragments(string key); +`} + + + +| Method | Description | +|------------------|-------------------------------------------------------------------------------------------------------| +| **GetFragments** | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key. | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_highlight-query-results-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx new file mode 100644 index 0000000000..79c9948921 --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-nodejs.mdx @@ -0,0 +1,339 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a __list of text fragments that highlight the searched terms__. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a __dynamic-query__. + For highlighting search results when querying a __static-index__ see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +// Define a param that will get the highlighted text fragments +let salesHighlights; + +const employeesResults = await session + // Make a dynamic query on 'Employees' collection + .query({ collection: "Employees" }) + // Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight' + .highlight({ + fieldName: 'Notes', // The document-field name in which we search + fragmentLength: 35, // Max length of each text fragment + fragmentCount: 4 }, // Max number of fragments to return per document + x => { salesHighlights = x; }) // Output param 'salesHighlights' will be filled + // with the highlighted text fragments when query returns. + // Execute the query + .all(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +let fragmentsHtml = "
    "; + +employeesResults.forEach((employee) => \{ + // Call 'getFragments' to get all fragments for the specified employee id + let fragments = salesHighlights.getFragments(employee.id); + + fragments.forEach((fragment) => \{ + fragmentsHtml += \`
  • Doc: $\{employee.id\} Fragment: $\{fragment\}
    • \`; + \}); +\}); + +fragmentsHtml += "
"; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. __Auto-Index__ + This is the auto-index that was created by the server to serve the dynamic-query. + +2. __Results tab__ + The results tab contains the resulting __documents__ that match the provided RQL query. + +3. __Highlight tab__ + The highlight tab shows the resulting __fragments__ that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be __customized__ to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= +const tagsToUse = { + preTags: ["+++", "<<<"], + postTags: ["+++", ">>>"] +}; + +// Make a full-text search dynamic query: +// ====================================== +let salesHighlights; +let managerHighlights; + +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + // Call 'highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight({ fieldName: 'Notes', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { salesHighlights = x; }) + .highlight({ fieldName: 'Title', fragmentLength: 35, fragmentCount: 1, ...tagsToUse }, + x => { managerHighlights = x; }) + .all(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== + +// Define a param that will get the highlighted text fragments +let termsHighlights; + +// Define the class for the projected results +class Result { + constructor () { + this.Name = null; + this.Title = null; + } +} + +// Make a dynamic query on 'Employees' collection +const employeesResults = await session + .query({ collection: "Employees" }) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + .search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + .highlight({ fieldName: "Notes", fragmentLength: 35, fragmentCount: 2 }, + x => { termsHighlights = x; }) + // Define the projection + .selectFields(QueryData.customFunction("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }" ), + Result) + .all(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`highlight(parameters, hightlightingsCallback); +`} + + + +| Parameter | Type | Description | +|----------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __parameters__ | `HighlightingParameters` | Parameters for the highlight method. | +| __hightlightingsCallback__ | `(highlightResults) => void)` | A callback function with an output parameter.
The parameter passed to the callback will be filled with the `Highlightings` object when query returns. | + +
+ +__The Highlighting parameters:__ + +| Parameter | Type | Description | +|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __fieldName__ | string | Name of the field that contains the searched terms to highlight. | +| __fragmentLength__ | number | Maximum length of a text fragment. Must be `>= 18`. | +| __fragmentCount__ | number | Maximum number of text fragments that will be returned. | +| __groupKey__ | string | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `null` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| __preTags__ | string[] | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| __postTags__ | string[] | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +__The Highlightings object__: + + + +{`class Highlightings \{ + // Name of the field that contains the searched terms to highlight. + get fieldName(); + // The resulting keys (document IDs, or the map-reduce keys) + get resultIndents(); + // Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key + getFragments(key); +\} +`} + + + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx new file mode 100644 index 0000000000..e2ca2649ef --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-php.mdx @@ -0,0 +1,359 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`// Make a full-text search dynamic query: +// ====================================== + +$highlightings = new Highlightings(); + +/** @var array $employeesResults */ +$employeesResults = $session + // Make a dynamic query on 'Employees' collection + ->query(Employee::class) + // Search for documents containing the term 'sales' in their 'Notes' field + ->search("Notes", "sales") + // Request to highlight the searched term by calling 'highlight()' + ->highlight( + "Notes", // The document-field name in which we search + 35, // Max length of each text fragment + 4, // Max number of fragments to return per document + null, // Put null to use default options + $highlightings) // An out param for getting the highlighted text fragments + + // Execute the query + ->toList(); +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`// Process results: +// ================ + +// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term. + +$builder = '
    '; + +/** @var SearchItem $employee */ +foreach ($employeesResults as $employee) \{ + // Call 'GetFragments' to get all fragments for the specified employee Id + $fragments = $highlightings->getFragments($employee->getId()); + foreach ($fragments as $fragment) \{ + $builder .= '
  • Doc: ' . $employee->getId() . ' Fragment: ' . $fragment . '
    • '; + \} +\} + +$builder .= '
'; +$fragmentsHtml = $builder; + +// The resulting fragmentsHtml: +// ============================ + +//
    +//
  • Doc: employees/2-A Fragment: company as a sales
    • +//
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +//
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +//
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +//
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +//
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +//
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +//
  • Doc: employees/5-A Fragment: Sales Management."
    • +//
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +//
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`// Define customized tags to use for highlighting the searched terms +// ================================================================= + +$salesHighlights = new Highlightings(); +$managerHighlights = new Highlightings(); + +$tagsToUse = new HighlightingOptions(); +// Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: +// the first term searched for will be wrapped with '+++' +// the second term searched for will be wrapped with '<<<' & '>>>' +$tagsToUse->setPreTags(["+++", "<<<"]); +$tagsToUse->setPostTags(["+++", ">>>"]); + +// Make a full-text search dynamic query: +// ====================================== +$employeesResults = $session + ->query(Employee::class) + // Search for: + // * documents containing the term 'sales' in their 'Notes' field + // * OR for documents containing the term 'manager' in their 'Title' field + ->search("Notes", "sales") + ->search("Title", "manager") + // Call 'Highlight' for each field searched + // Pass 'tagsToUse' to OVERRIDE the default tags used + ->highlight("Notes", 35, 1, $tagsToUse, $salesHighlights) + ->highlight("Title", 35, 1, $tagsToUse, $managerHighlights) + ->toList(); +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`// The resulting salesHighlights fragments: +// ======================================== + +// "for the +++Sales+++ Professional." +// "hired as a +++sales+++ associate in" +// "company as a +++sales+++" +// "company as a +++sales+++ representativ" + +// The resulting managerHighlights fragments: +// ========================================== + +// "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`// Make a full-text search dynamic query & project results: +// ======================================================== +$termsHighlights = new Highlightings(); + +/** @var array $employeesProjectedResults */ +$employeesProjectedResults = $session + ->query(Employee::class) + // Search for documents containing 'sales' or 'german' in their 'Notes' field + ->search("Notes", "manager german") + // Request to highlight the searched terms from the 'Notes' field + ->highlight("Notes", 35, 2, null, $termsHighlights) + // Define the projection + ->selectFields(EmployeeDetails::class, QueryData::customFunction("o", "{ name: o.FirstName + ' ' + o.LastName, title: o.Title }")) + ->toList(); +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`// The resulting fragments from termsHighlights: +// ============================================= + +// "to sales manager in March" +// "and reads German. He joined" +// "to sales manager in January" +// "in French and German." + +// NOTE: each search term is wrapped with a different color +// 'manager' is wrapped with yellow +// 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`function highlight( + ?string $fieldName, + int $fragmentLength, + int $fragmentCount, + ?HighlightingOptions $options, + Highlightings &$highlightings +): DocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **$fragmentLength** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **$fragmentCount** | `int` | Maximum number of text fragments that will be returned | +| **$options** | `?HighlightingOptions ` | Customizing options | +| **&$highlightings** | `Highlightings` | A callback function to retrieve the highlighted text fragments for each returned result | + +
+ +**Highlighting options**: + + + +{`private ?string $groupKey; +private ?StringArray $preTags = null; +private ?StringArray $postTags = null; + +// getters and setters +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **$groupKey** | `?string` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **$preTags** | `?StringArray` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **$postTags** | `?StringArray` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`private ?string $fieldName = null; +public function getResultIndents(): array; +`} + + + +| Property | Type | Description | +|--------------------|------------|-------------| +| **$fieldName** | `?string` | Name of the field that contains the searched terms to highlight | +| **getResultIndents()** | function returning an `array` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`public function getFragments(?string $key): array; +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|-------------| +| **getFragments(?string $key)** | function returning an `array` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx new file mode 100644 index 0000000000..5f5eb3a82e --- /dev/null +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_highlight-query-results-python.mdx @@ -0,0 +1,370 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* When making a [Full-Text Search query](../../../../client-api/session/querying/text-search/full-text-search.mdx), + in addition to retrieving documents that contain the searched terms in the results, + you can also request to get a **list of text fragments that highlight the searched terms**. + +* The highlighted terms can enhance user experience when searching for documents with specific content. + +* This article shows highlighting search results when making a **dynamic-query**. + For highlighting search results when querying a **static-index** see [highlight index search results](../../../../indexes/querying/highlighting.mdx). +* In this page: + * [Highlight - basic example](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---basic-example) + * [Highlight tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-tags) + * [Highlight results in Studio](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight-results-in-studio) + * [Highlight - customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) + * [Highlight - projected results](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---projected-results) + * [Syntax](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#syntax) + + +## Highlight - basic example + + + + +{`# Make a full-text search dynamic query: +# ====================================== + +# Define a callback that takes highlightings as an argument +sales_highlightings: Optional[Highlightings] = None + +def _sales_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + sales_highlightings = highlightings + +employees_result = list( # Execute the query inside the parenthesis + session + # Make a query on 'Employees' collection + .query(object_type=Employee) + # Search for documents containing the term 'sales' in their 'Notes' field + .search("Notes", "sales") + # Request to highlight the searched term by calling 'Highlight' + .highlight( + "Notes", # The document-field name in which we search + 35, # Max length of each text fragment + 4, # Max number of fragments to return per document + _sales_highlights, # An out param for getting the highlighted text fragments + ) +) +`} + + + + +{`from "Employees" +where search(Notes, "sales") +include highlight(Notes, 35, 4) +`} + + + + + + +{`# Process results: +# ================ + +# 'employees_results' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field. +# 'sales_highlights' contains the text FRAGMENTS that highlight the 'sales' term. + +builder = ["
    ", \{os.linesep\}] +for employee in employees_result: + # Call 'get_fragments' to get all fragments for the specified employee Id + fragments = sales_highlightings.get_fragments(employee.Id) + for fragment in fragments: + builder.append(f"\{os.linesep\}
  • Doc: \{employee.Id\} Fragment: \{fragment\}
    • ") + +fragments_html = builder.append(f"\{os.linesep\}
") + +# The resulting fragments_html: +# ============================ + +#
    +#
  • Doc: employees/2-A Fragment: company as a sales
    • +#
  • Doc: employees/2-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/2-A Fragment: president of sales in March 1993
    • +#
  • Doc: employees/2-A Fragment: member of the Sales Management
    • +#
  • Doc: employees/3-A Fragment: hired as a sales associate in
    • +#
  • Doc: employees/3-A Fragment: promoted to sales representativ
    • +#
  • Doc: employees/5-A Fragment: company as a sales representativ
    • +#
  • Doc: employees/5-A Fragment: promoted to sales manager in
    • +#
  • Doc: employees/5-A Fragment: Sales Management."
    • +#
  • Doc: employees/6-A Fragment: for the Sales Professional.
    • +#
+`} + + + + + +#### Highlight tags + +* By default, the highlighted term is wrapped with the following html: + `term` + +* When requesting to highlight multiple terms, + the background color returned for each different term will be in the following order: + + - <span style="border-left: 10px solid yellow"> </span>yellow, + - <span style="border-left: 10px solid lawngreen"> </span>lawngreen, + - <span style="border-left: 10px solid aquamarine"> </span>aquamarine, + - <span style="border-left: 10px solid magenta"> </span>magenta, + - <span style="border-left: 10px solid palegreen"> </span>palegreen, + - <span style="border-left: 10px solid coral"> </span>coral, + - <span style="border-left: 10px solid wheat"> </span>wheat, + - <span style="border-left: 10px solid khaki"> </span>khaki, + - <span style="border-left: 10px solid lime"> </span>lime, + - <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue, + - <span style="border-left: 10px solid deeppink"> </span>deeppink, + - <span style="border-left: 10px solid salmon"> </span>salmon, + - <span style="border-left: 10px solid peachpuff"> </span>peachpuff, + - <span style="border-left: 10px solid violet"> </span>violet, + - <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple, + - <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod, + - <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki, + - <span style="border-left: 10px solid springgreen"> </span>springgreen, + - <span style="border-left: 10px solid turquoise"> </span>turquoise, + - <span style="border-left: 10px solid powderblue"> </span>powderblue + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + See [customize tags](../../../../client-api/session/querying/text-search/highlight-query-results.mdx#highlight---customize-tags) below. + + + + + +#### Highlight results in Studio + +![Figure 1. Fragments results](../assets/fragmentsResults.png) + +1. **Auto-Index** + This is the auto-index that was created by the server to serve the dynamic-query. + +2. **Results tab** + The results tab contains the resulting **documents** that match the provided RQL query. + +3. **Highlight tab** + The highlight tab shows the resulting **fragments** that were included in the query result. + + + + + +## Highlight - customize tags + +* The html tags that wrap the highlighted terms can be **customized** to any other tags. + + + + +{`# Define customized tags to use for highlighting the searched terms +# ================================================================= +tags_to_use = HighlightingOptions( + # Provide strings of your choice to 'PreTags' & 'PostTags', e.g.: + # the first term searched for will be wrapped with '+++' + # the second term searched for will be wrapped with '<<<' & '>>>' + pre_tags=["+++", "<<<"], + post_tags=["+++", ">>>"], +) + +# Define a callback that takes highlightings as an argument +manager_highlightings: Optional[Highlightings] = None + +def _manager_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + manager_highlightings = highlightings + +# Make a full-text search dynamic query: +# ====================================== +employees_result = list( + session.query(object_type=Employee) + # Search for: + # * documents containing the term 'sales' in their 'Notes' field + # * OR for documents containing the term 'manager' in their 'Title' field + .search("Notes", "sales") + .search("Title", "manager") + # Call 'Highlight' for each field searched + # Pass 'tagsToUse' to OVERRIDE the default tags used + .highlight("Notes", 35, 1, _sales_highlights) + .highlight("Title", 35, 1, tags_to_use, _manager_highlights) +) +`} + + + + +{`from "Employees" +where (search(Notes, "sales") or search(Title, "manager")) +include highlight(Notes, 35, 1, $p0), highlight(Title, 35, 1, $p1) +{ +"p0":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]}, +"p1":{"PreTags":["+++","<<<"],"PostTags":["+++",">>>"]} +} +`} + + + + + + +{`# The resulting salesHighlights fragments: +# ======================================== +# +# "for the +++Sales+++ Professional." +# "hired as a +++sales+++ associate in" +# "company as a +++sales+++" +# "company as a +++sales+++ representative" +# +# The resulting managerHighlights fragments: +# ========================================== +# +# "Sales <<>>" +`} + + + + + +## Highlight - projected results + +* Highlighting can also be used when [projecting query results](../../../../client-api/session/querying/how-to-project-query-results.mdx). + + + + +{`# Make a full-text search dynamic query & project results: +# ======================================================== + +# Define a callback that takes highlightings as an argument +terms_highlightings: Optional[Highlightings] = None + +def _terms_highlights(highlightings: Highlightings): + # You may use the results (highlightings) here in any way desired + terms_highlightings = highlightings + +employees_projected = list( + session.query(object_type=Employee) + .search("Notes", "manager german") + .highlight("Notes", 35, 2, _terms_highlights) + .select_fields_query_data( + QueryData.custom_function("o", "{ Name: o.FirstName + ' ' + o.LastName, Title: o.Title }"), + ) +) + +`} + + + + +{`from "Employees" as x +where search(x.Notes, "manager german") +select { Name : "{0} {1}".format(x.FirstName, x.LastName), Title : x.Title } +include highlight(Notes, 35, 2) +`} + + + + + + +{`# The resulting fragments from termsHighlights: +# ============================================= +# +# "to sales manager in March" +# "and reads German. He joined" +# "to sales manager in January" +# "in French and German." +# +# NOTE: each search term is wrapped with a different color +# 'manager' is wrapped with yellow +# 'german' is wrapped with lawngreen +`} + + + + + +## Syntax + + + +{`def highlight( + self, + field_name: str, + fragment_length: int, + fragment_count: int, + highlightings_callback: Callable[[Highlightings], None], + options: Optional[HighlightingOptions] = None, +) -> DocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|--------------------|-------------------------------|-------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **fragment_length** | `int` | Maximum length of a text fragment
Must be `>= 18` | +| **fragment_count** | `int` | Maximum number of text fragments that will be returned | +| **highlightings_callback** | `Callable[[Highlightings], None]` | A callback function to retrieve the highlighted text fragments for each returned result | +| **options** (Optional) | `HighlightingOptions ` | Customizing options | + +
+ +**Highlighting options**: + + + +{`def __init__(self, group_key: str = None, pre_tags: List[str] = None, post_tags: List[str] = None): + self.group_key = group_key + self.pre_tags = pre_tags + self.post_tags = post_tags +`} + + + +| Option | Type | Description | +|--------------|-----------|--------------| +| **group_key** | `str` | Grouping key for the results.
Used when highlighting query results from a [Map-Reduce index](../../../../indexes/querying/highlighting.mdx#highlight-results---map-reduce-index).
If `None` results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries. | +| **pre_tags** | `List[str]` | Array of PRE tags used to wrap the highlighted search terms in the text fragments. | +| **post_tags** | `List[str]` | Array of POST tags used to wrap the highlighted search terms in the text fragments. | + +
+ +**Highlightings object**: + + + +{`def __init__(self, field_name: str): + self.field_name = field_name + ... + +@property +def result_indents(self) -> Set[str]: ... +`} + + + +| Property | Type | Description | +|--------------------|------------|-----------------------------------------------------------------| +| **field_name** | `str` | Name of the field that contains the searched terms to highlight | +| **result_indents** | `Set[str]` | The resulting keys (document IDs, or the map-reduce keys) | + + + +{`def get_fragments(self, key: str) -> List[str]: ... +`} + + + +| Method | Return Type | Description | +|-------------------|-------------|------------------------------------------------------------------------------------------------------| +| **get_fragments** | `List[str]` | Returns the list of the highlighted text fragments for the passed document ID, or the map-reduce key | + + + + diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_proximity-search-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_proximity-search-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_starts-with-query-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_starts-with-query-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-csharp.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-csharp.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-java.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-java.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-java.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-nodejs.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-nodejs.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-php.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-php.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-php.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-php.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-python.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-python.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/session/querying/text-search/_using-regex-python.mdx rename to versioned_docs/version-7.1/client-api/session/querying/text-search/content/_using-regex-python.mdx diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/ends-with-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/ends-with-query.mdx index 9de7b76eba..73a404cbd1 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/ends-with-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/ends-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EndsWithQueryCsharp from './_ends-with-query-csharp.mdx'; -import EndsWithQueryPython from './_ends-with-query-python.mdx'; -import EndsWithQueryPhp from './_ends-with-query-php.mdx'; -import EndsWithQueryNodejs from './_ends-with-query-nodejs.mdx'; +import EndsWithQueryCsharp from './content/_ends-with-query-csharp.mdx'; +import EndsWithQueryPython from './content/_ends-with-query-python.mdx'; +import EndsWithQueryPhp from './content/_ends-with-query-php.mdx'; +import EndsWithQueryNodejs from './content/_ends-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/exact-match-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/exact-match-query.mdx index 6a40d3ad41..40374970af 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/exact-match-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/exact-match-query.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExactMatchQueryCsharp from './_exact-match-query-csharp.mdx'; -import ExactMatchQueryJava from './_exact-match-query-java.mdx'; -import ExactMatchQueryPython from './_exact-match-query-python.mdx'; -import ExactMatchQueryPhp from './_exact-match-query-php.mdx'; -import ExactMatchQueryNodejs from './_exact-match-query-nodejs.mdx'; +import ExactMatchQueryCsharp from './content/_exact-match-query-csharp.mdx'; +import ExactMatchQueryJava from './content/_exact-match-query-java.mdx'; +import ExactMatchQueryPython from './content/_exact-match-query-python.mdx'; +import ExactMatchQueryPhp from './content/_exact-match-query-php.mdx'; +import ExactMatchQueryNodejs from './content/_exact-match-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/full-text-search.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/full-text-search.mdx index ebc67ec9da..6bc5c4010c 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/full-text-search.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/full-text-search.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FullTextSearchCsharp from './_full-text-search-csharp.mdx'; -import FullTextSearchPython from './_full-text-search-python.mdx'; -import FullTextSearchPhp from './_full-text-search-php.mdx'; -import FullTextSearchNodejs from './_full-text-search-nodejs.mdx'; +import FullTextSearchCsharp from './content/_full-text-search-csharp.mdx'; +import FullTextSearchPython from './content/_full-text-search-python.mdx'; +import FullTextSearchPhp from './content/_full-text-search-php.mdx'; +import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/fuzzy-search.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/fuzzy-search.mdx index 4726607af2..3b6f870387 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/fuzzy-search.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/fuzzy-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FuzzySearchCsharp from './_fuzzy-search-csharp.mdx'; -import FuzzySearchJava from './_fuzzy-search-java.mdx'; -import FuzzySearchPython from './_fuzzy-search-python.mdx'; -import FuzzySearchPhp from './_fuzzy-search-php.mdx'; -import FuzzySearchNodejs from './_fuzzy-search-nodejs.mdx'; +import FuzzySearchCsharp from './content/_fuzzy-search-csharp.mdx'; +import FuzzySearchJava from './content/_fuzzy-search-java.mdx'; +import FuzzySearchPython from './content/_fuzzy-search-python.mdx'; +import FuzzySearchPhp from './content/_fuzzy-search-php.mdx'; +import FuzzySearchNodejs from './content/_fuzzy-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/highlight-query-results.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/highlight-query-results.mdx index 0821c42f6d..f201114279 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/highlight-query-results.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/highlight-query-results.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightQueryResultsJava from './_highlight-query-results-java.mdx'; -import HighlightQueryResultsCsharp from './_highlight-query-results-csharp.mdx'; -import HighlightQueryResultsPython from './_highlight-query-results-python.mdx'; -import HighlightQueryResultsPhp from './_highlight-query-results-php.mdx'; -import HighlightQueryResultsNodejs from './_highlight-query-results-nodejs.mdx'; +import HighlightQueryResultsJava from './content/_highlight-query-results-java.mdx'; +import HighlightQueryResultsCsharp from './content/_highlight-query-results-csharp.mdx'; +import HighlightQueryResultsPython from './content/_highlight-query-results-python.mdx'; +import HighlightQueryResultsPhp from './content/_highlight-query-results-php.mdx'; +import HighlightQueryResultsNodejs from './content/_highlight-query-results-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/proximity-search.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/proximity-search.mdx index 3413fee351..b1c07552b2 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/proximity-search.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/proximity-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProximitySearchCsharp from './_proximity-search-csharp.mdx'; -import ProximitySearchJava from './_proximity-search-java.mdx'; -import ProximitySearchPython from './_proximity-search-python.mdx'; -import ProximitySearchPhp from './_proximity-search-php.mdx'; -import ProximitySearchNodejs from './_proximity-search-nodejs.mdx'; +import ProximitySearchCsharp from './content/_proximity-search-csharp.mdx'; +import ProximitySearchJava from './content/_proximity-search-java.mdx'; +import ProximitySearchPython from './content/_proximity-search-python.mdx'; +import ProximitySearchPhp from './content/_proximity-search-php.mdx'; +import ProximitySearchNodejs from './content/_proximity-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/starts-with-query.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/starts-with-query.mdx index 5b1e30b092..4a1b0043fa 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/starts-with-query.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/starts-with-query.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StartsWithQueryCsharp from './_starts-with-query-csharp.mdx'; -import StartsWithQueryPython from './_starts-with-query-python.mdx'; -import StartsWithQueryPhp from './_starts-with-query-php.mdx'; -import StartsWithQueryNodejs from './_starts-with-query-nodejs.mdx'; +import StartsWithQueryCsharp from './content/_starts-with-query-csharp.mdx'; +import StartsWithQueryPython from './content/_starts-with-query-python.mdx'; +import StartsWithQueryPhp from './content/_starts-with-query-php.mdx'; +import StartsWithQueryNodejs from './content/_starts-with-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/text-search/using-regex.mdx b/versioned_docs/version-7.1/client-api/session/querying/text-search/using-regex.mdx index 3b30fb0e45..bf6fe65504 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/text-search/using-regex.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/text-search/using-regex.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingRegexCsharp from './_using-regex-csharp.mdx'; -import UsingRegexJava from './_using-regex-java.mdx'; -import UsingRegexPython from './_using-regex-python.mdx'; -import UsingRegexPhp from './_using-regex-php.mdx'; -import UsingRegexNodejs from './_using-regex-nodejs.mdx'; +import UsingRegexCsharp from './content/_using-regex-csharp.mdx'; +import UsingRegexJava from './content/_using-regex-java.mdx'; +import UsingRegexPython from './content/_using-regex-python.mdx'; +import UsingRegexPhp from './content/_using-regex-php.mdx'; +import UsingRegexNodejs from './content/_using-regex-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/querying/vector-search.mdx b/versioned_docs/version-7.1/client-api/session/querying/vector-search.mdx index 49709640a7..19b0fe51a4 100644 --- a/versioned_docs/version-7.1/client-api/session/querying/vector-search.mdx +++ b/versioned_docs/version-7.1/client-api/session/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/saving-changes.mdx b/versioned_docs/version-7.1/client-api/session/saving-changes.mdx index ea4dca8cdb..8b87a0f6a3 100644 --- a/versioned_docs/version-7.1/client-api/session/saving-changes.mdx +++ b/versioned_docs/version-7.1/client-api/session/saving-changes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SavingChangesCsharp from './_saving-changes-csharp.mdx'; -import SavingChangesJava from './_saving-changes-java.mdx'; -import SavingChangesPython from './_saving-changes-python.mdx'; -import SavingChangesPhp from './_saving-changes-php.mdx'; -import SavingChangesNodejs from './_saving-changes-nodejs.mdx'; +import SavingChangesCsharp from './content/_saving-changes-csharp.mdx'; +import SavingChangesJava from './content/_saving-changes-java.mdx'; +import SavingChangesPython from './content/_saving-changes-python.mdx'; +import SavingChangesPhp from './content/_saving-changes-php.mdx'; +import SavingChangesNodejs from './content/_saving-changes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/storing-entities.mdx b/versioned_docs/version-7.1/client-api/session/storing-entities.mdx index b772d50513..56ba87d350 100644 --- a/versioned_docs/version-7.1/client-api/session/storing-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/storing-entities.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringEntitiesCsharp from './_storing-entities-csharp.mdx'; -import StoringEntitiesJava from './_storing-entities-java.mdx'; -import StoringEntitiesPython from './_storing-entities-python.mdx'; -import StoringEntitiesPhp from './_storing-entities-php.mdx'; -import StoringEntitiesNodejs from './_storing-entities-nodejs.mdx'; +import StoringEntitiesCsharp from './content/_storing-entities-csharp.mdx'; +import StoringEntitiesJava from './content/_storing-entities-java.mdx'; +import StoringEntitiesPython from './content/_storing-entities-python.mdx'; +import StoringEntitiesPhp from './content/_storing-entities-php.mdx'; +import StoringEntitiesNodejs from './content/_storing-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/updating-entities.mdx b/versioned_docs/version-7.1/client-api/session/updating-entities.mdx index 8cfe9a7d3f..2004061e06 100644 --- a/versioned_docs/version-7.1/client-api/session/updating-entities.mdx +++ b/versioned_docs/version-7.1/client-api/session/updating-entities.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UpdatingEntitiesCsharp from './_updating-entities-csharp.mdx'; -import UpdatingEntitiesPython from './_updating-entities-python.mdx'; -import UpdatingEntitiesPhp from './_updating-entities-php.mdx'; -import UpdatingEntitiesNodejs from './_updating-entities-nodejs.mdx'; +import UpdatingEntitiesCsharp from './content/_updating-entities-csharp.mdx'; +import UpdatingEntitiesPython from './content/_updating-entities-python.mdx'; +import UpdatingEntitiesPhp from './content/_updating-entities-php.mdx'; +import UpdatingEntitiesNodejs from './content/_updating-entities-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx b/versioned_docs/version-7.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx index a5ff85f8e9..9b84aa211c 100644 --- a/versioned_docs/version-7.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx +++ b/versioned_docs/version-7.1/client-api/session/what-is-a-session-and-how-does-it-work.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsASessionAndHowDoesItWorkCsharp from './_what-is-a-session-and-how-does-it-work-csharp.mdx'; -import WhatIsASessionAndHowDoesItWorkJava from './_what-is-a-session-and-how-does-it-work-java.mdx'; -import WhatIsASessionAndHowDoesItWorkPython from './_what-is-a-session-and-how-does-it-work-python.mdx'; -import WhatIsASessionAndHowDoesItWorkPhp from './_what-is-a-session-and-how-does-it-work-php.mdx'; -import WhatIsASessionAndHowDoesItWorkNodejs from './_what-is-a-session-and-how-does-it-work-nodejs.mdx'; +import WhatIsASessionAndHowDoesItWorkCsharp from './content/_what-is-a-session-and-how-does-it-work-csharp.mdx'; +import WhatIsASessionAndHowDoesItWorkJava from './content/_what-is-a-session-and-how-does-it-work-java.mdx'; +import WhatIsASessionAndHowDoesItWorkPython from './content/_what-is-a-session-and-how-does-it-work-python.mdx'; +import WhatIsASessionAndHowDoesItWorkPhp from './content/_what-is-a-session-and-how-does-it-work-php.mdx'; +import WhatIsASessionAndHowDoesItWorkNodejs from './content/_what-is-a-session-and-how-does-it-work-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/setting-up-authentication-and-authorization.mdx b/versioned_docs/version-7.1/client-api/setting-up-authentication-and-authorization.mdx index ed0f1ec2b4..8d3f04124a 100644 --- a/versioned_docs/version-7.1/client-api/setting-up-authentication-and-authorization.mdx +++ b/versioned_docs/version-7.1/client-api/setting-up-authentication-and-authorization.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpAuthenticationAndAuthorizationCsharp from './_setting-up-authentication-and-authorization-csharp.mdx'; -import SettingUpAuthenticationAndAuthorizationJava from './_setting-up-authentication-and-authorization-java.mdx'; -import SettingUpAuthenticationAndAuthorizationNodejs from './_setting-up-authentication-and-authorization-nodejs.mdx'; +import SettingUpAuthenticationAndAuthorizationCsharp from './content/_setting-up-authentication-and-authorization-csharp.mdx'; +import SettingUpAuthenticationAndAuthorizationJava from './content/_setting-up-authentication-and-authorization-java.mdx'; +import SettingUpAuthenticationAndAuthorizationNodejs from './content/_setting-up-authentication-and-authorization-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/setting-up-default-database.mdx b/versioned_docs/version-7.1/client-api/setting-up-default-database.mdx index 182fc9c2f2..f6ba4e7692 100644 --- a/versioned_docs/version-7.1/client-api/setting-up-default-database.mdx +++ b/versioned_docs/version-7.1/client-api/setting-up-default-database.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SettingUpDefaultDatabaseCsharp from './_setting-up-default-database-csharp.mdx'; -import SettingUpDefaultDatabaseJava from './_setting-up-default-database-java.mdx'; -import SettingUpDefaultDatabaseNodejs from './_setting-up-default-database-nodejs.mdx'; +import SettingUpDefaultDatabaseCsharp from './content/_setting-up-default-database-csharp.mdx'; +import SettingUpDefaultDatabaseJava from './content/_setting-up-default-database-java.mdx'; +import SettingUpDefaultDatabaseNodejs from './content/_setting-up-default-database-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-csharp.mdx b/versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-csharp.mdx rename to versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-csharp.mdx diff --git a/versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-java.mdx b/versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-java.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-java.mdx rename to versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-java.mdx diff --git a/versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-nodejs.mdx b/versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/client-api/smuggler/_what-is-smuggler-nodejs.mdx rename to versioned_docs/version-7.1/client-api/smuggler/content/_what-is-smuggler-nodejs.mdx diff --git a/versioned_docs/version-7.1/client-api/smuggler/what-is-smuggler.mdx b/versioned_docs/version-7.1/client-api/smuggler/what-is-smuggler.mdx index 756dce6468..04d7b18837 100644 --- a/versioned_docs/version-7.1/client-api/smuggler/what-is-smuggler.mdx +++ b/versioned_docs/version-7.1/client-api/smuggler/what-is-smuggler.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsSmugglerCsharp from './_what-is-smuggler-csharp.mdx'; -import WhatIsSmugglerJava from './_what-is-smuggler-java.mdx'; -import WhatIsSmugglerNodejs from './_what-is-smuggler-nodejs.mdx'; +import WhatIsSmugglerCsharp from './content/_what-is-smuggler-csharp.mdx'; +import WhatIsSmugglerJava from './content/_what-is-smuggler-java.mdx'; +import WhatIsSmugglerNodejs from './content/_what-is-smuggler-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/client-api/what-is-a-document-store.mdx b/versioned_docs/version-7.1/client-api/what-is-a-document-store.mdx index fd0b6a4ca6..549c766cf4 100644 --- a/versioned_docs/version-7.1/client-api/what-is-a-document-store.mdx +++ b/versioned_docs/version-7.1/client-api/what-is-a-document-store.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatIsADocumentStoreCsharp from './_what-is-a-document-store-csharp.mdx'; -import WhatIsADocumentStoreJava from './_what-is-a-document-store-java.mdx'; -import WhatIsADocumentStoreNodejs from './_what-is-a-document-store-nodejs.mdx'; +import WhatIsADocumentStoreCsharp from './content/_what-is-a-document-store-csharp.mdx'; +import WhatIsADocumentStoreJava from './content/_what-is-a-document-store-java.mdx'; +import WhatIsADocumentStoreNodejs from './content/_what-is-a-document-store-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/data-archival/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-7.1/data-archival/_archived-documents-and-other-features-csharp.mdx deleted file mode 100644 index 833b403537..0000000000 --- a/versioned_docs/version-7.1/data-archival/_archived-documents-and-other-features-csharp.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), - RavenDB features can detect these documents and handle them in different ways. - -* Some features, like indexes and data subscriptions, provide native support for configuring whether to: - * **Exclude** archived documents from processing, reducing index size and improving query relevance. - * **Include** only archived documents, for tasks that target archived data specifically. - * **Process both** archived and non-archived documents when needed. - -* Other features can manage archived documents differently based on their purpose. For example: - * ETL tasks can skip or selectively process archived documents. - * Archived documents can be included or excluded when exporting or importing data. - -* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. - -* Learn more below about how various RavenDB features interact with archived documents. -* In this article: - * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) - * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) - * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) - * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) - * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) - * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) - * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) - * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) - * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) - * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) - - -## Archived documents and indexing - -* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. -* Archiving documents and excluding them from indexing can be an effective way to maintain performance. - By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. - This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. -* **Configuring indexing behavior - Static indexes**: - * **At the database level or server-wide**: - To control whether static indexes process archived documents from the source collection, - set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) - configuration key at either the database level or server-wide (default: `ExcludeArchived`). - * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. - This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. - * **Per index**: - You can override this global behavior per-index directly in the index definition, using the Client API from the Studio - (see the examples below). - -* **Configuring indexing behavior - Auto indexes:** - * **At the database level or server-wide**: - To control whether auto-indexes process archived documents at the database level or server-wide, - set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). - * **Per index**: - Unlike static indexes, you cannot configure this behavior per auto-index, - because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the index. - * `IncludeArchived`: both archived and non-archived documents are processed by the index. - * `ArchivedOnly`: only archived documents are processed by the index. -##### Configuring archived document processing for a static index - from the Client API - -You can configure how a static index handles archived documents when creating the index using the Client API. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`public class Orders_ByOrderDate : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public DateTime OrderDate { get; set; } - } - - public Orders_ByOrderDate() - { - Map = orders => from order in orders - select new IndexEntry - { - OrderDate = order.OrderedAt - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByOrderDate_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - return { - OrderDate: order.OrderedAt - }; - })" - }; - - // Configure whether the index should process data from archived documents: - // ======================================================================== - ArchivedDataProcessingBehavior = - // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinitionBuilder() -{ - Map = orders => from order in orders - select new { order.OrderedAt } -} - .ToIndexDefinition(new DocumentConventions()); - -indexDefinition.Name = "Orders/ByOrderDate"; - -// Configure whether the index should process data from archived documents: -// ======================================================================== -indexDefinition.ArchivedDataProcessingBehavior = - // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' - ArchivedDataProcessingBehavior.IncludeArchived; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - - -When a static-index is configured to include **both** archived and non-archived documents in its processing, -you can also apply custom logic based on the presence of the `@archived` metadata property. - -For example: - - - - -{`public class Orders_ByArchivedStatus : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public bool? isArchived { get; set; } - public DateTime? OrderDate { get; set; } - public string ShipToCountry { get; set; } - } - - public Orders_ByArchivedStatus() - { - Map = orders => from order in orders - let metadata = MetadataFor(order) - - // Retrieve the '@archived' metadata property from the document: - let archivedProperty = - metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) - // Alternative syntax: - // let archivedProperty = - // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] - - select new IndexEntry - { - // Index whether the document is archived: - isArchived = archivedProperty == true, - - // Index the order date only if the document is archived: - OrderDate = archivedProperty == true ? order.OrderedAt : null, - - // Index the destination country only if the document is not archived: - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask -{ - public Orders_ByArchivedStatus_JS() - { - Maps = new HashSet() - { - @"map('Orders', function (order) { - var metadata = metadataFor(order); - var archivedProperty = metadata['@archived']; - - var isArchived = (archivedProperty === true); - - var orderDate = isArchived ? order.OrderedAt : null; - var shipToCountry = !isArchived ? order.ShipTo.Country : null; - - return { - IsArchived: isArchived, - OrderDate: orderDate, - ShipToCountry: shipToCountry - }; - })" - }; - - ArchivedDataProcessingBehavior = - Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "Orders/ByArchivedStatus", - - Maps = new HashSet - { - @"from order in docs.Orders - let metadata = MetadataFor(order) - let archivedProperty = (bool?)metadata[""@archived""] - - select new - { - IsArchived = archivedProperty == true, - OrderDate = archivedProperty == true ? order.OrderedAt : null, - ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null - }" - }, - - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - -##### Configuring archived document processing for a static index - from the Studio - -You can configure how a static index handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. - -![Configure index](./assets/configure-static-index.png) - -1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, - or create a new index. -2. Scroll down and open the **Archived Data** tab. -3. Click to select how this index should process archived documents: - * **Default**: The index will use the behavior set by the global configuration. - * **Exclude Archived**: Index only non-archived documents. - * **Include Archived**: Index both archived and non-archived documents. - * **Archived Only**: Index only archived documents. - -![Processing options](./assets/processing-options.png) - - - -## Archived documents and querying - -* **Full collection queries**: - * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. - * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. - * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). - -* **Dynamic queries (auto-indexes)**: - * When making a dynamic query, RavenDB creates an auto-index to serve it. - Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. - * Once created, the auto-index retains that behavior. - Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. - * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). - -* **Querying static-indexes**: - * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. - The index behavior is determined by: - * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - - * the explicit setting in the index definition, which overrides the global configuration key. - * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. - - - -## Archived documents and subscriptions - -* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. -* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. - This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. -* **Configuring the subscription task behavior**: - * **At the database level or server-wide**: - To control whether queries in data subscription tasks process archived documents, - set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide - (default: `ExcludeArchived`). - * **Per task**: - You can override this global behavior per data subscription task directly in the task definition, - using the Client API or from the Studio (see the examples below). -* The available configuration options are: - * `ExcludeArchived`: only non-archived documents are processed by the subscription query. - * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. - * `ArchivedOnly`: only archived documents are processed by the subscription query. -##### Configuring archived document processing for a data subscription task - from the Client API - -You can configure how a subscription task handles archived documents when creating the subscription using the Client API. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - - - -Example: - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - -{`var subscriptionName = store.Subscriptions - .Create(new SubscriptionCreationOptions() -{ - Name = "ArchivedOrdersSubscription", - Query = "from Orders", - // Workers that will subscribe to this subscription task - // will receive only archived documents from the 'Orders' collection. - ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly - - // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' -}); -`} - - - - - -##### Configuring archived document processing for a data subscription task - from the Studio - -You can configure how a subscription task handles archived documents directly from the Studio. -This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. - -![Configure subscription](./assets/configure-subscription.png) - -1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, - or create a new subscription. -2. Click to select how the subscription query should process archived documents: - * **Default**: The subscription will use the behavior set by the global configuration. - * **Exclude Archived**: Process only non-archived documents. - * **Include Archived**: Process both archived and non-archived documents. - * **Archived Only**: Process only archived documents. - - - -## Archived documents and document extensions - -* **Attachments**: - * Attachments are Not archived (compressed), even if the document they belong to is archived. - -* **Counters**: - * Counters are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Time series**: - * Time series are Not archived (compressed), even if the document they belong to is archived. - * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - - indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). - This behavior can be modified in the index definition. - -* **Revisions**: - * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. - * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. - - - -## Archived documents and smuggler (export/import) - -You can control whether archived documents are included when exporting or importing a database. -##### Export/Import archived documents - from the Client API - -[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. -By default, archived documents are **included** in the operation. - - - -In this example, exported data **excludes** archived documents: - - - -{`var exportOperation = store.Smuggler.ExportAsync( - new DatabaseSmugglerExportOptions() - \{ - // Export only non-archived documents: - IncludeArchived = false - \}, "DestinationFilePath"); -`} - - - - - - - -In this example, imported data **includes** archived documents: - - - -{`var importOperation = store.Smuggler.ImportAsync( - new DatabaseSmugglerImportOptions() - \{ - // Include archived documents in the import: - IncludeArchived = true - \}, "SourceFilePath"); -`} - - - - -##### Export archived documents - from the Studio - -![Export archived documents](./assets/export-archived-documents.png) - -1. Go to **Tasks > Export Database**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. -##### Import archived documents - from the Studio - -![Import archived documents](./assets/import-archived-documents.png) - -1. Go to **Tasks > Import Data**. -2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. - - - -## Archived documents and expiration - -* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). - -* For example, a document can be scheduled to be archived after six months and expired after one year. - This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, - and eventually remove documents that are no longer needed. - -* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` - to schedule it for archiving and expiration, respectively: - - - -{`\{ - "Name": "Wilman Kala", - "Phone": "90-224 8858", - ... - "@metadata": \{ - "@archive-at": "2026-01-06T22:45:30.018Z", - "@expires": "2026-07-06T22:45:30.018Z", - "@collection": "Companies", - ... - \} -\} -`} - - - - - -## Archived documents and ETL - -* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) - for the existence of the `@archived: true` property, which indicates that the document is archived. - Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. - -* With [RavenDB ETL](../server/ongoing-tasks/etl/raven), documents that are archived in the source database and sent to the target - are not archived in the destination database. - -* In the following example, the ETL script checks whether the document is archived, and skips it if it is: - - - -{`var isArchived = this['@metadata']['@archived']; - -if (isArchived === true) \{ - return; // Do not process archived documents -\} - -// Transfer only non-archived documents to the target -loadToOrders(this); -`} - - - - - -## Archived documents and backup - -* Archived documents are included in database backups (both _logical backups_ and _snapshots_), - no special configuration is required. - -* When restoring a database from a backup, archived documents are restored as well, - and their archived status is preserved. - - - -## Archived documents and replication - -Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, -[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - -no special configuration is required. - - - -## Archived documents and patching - -* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: - [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). - [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). - -* Patching is used to **unarchive** documents. - See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). - -* When **cloning** an archived document using the `put` method within a patching script - (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, - and the `@archived: true` property will be removed from the cloned document. - - - - diff --git a/versioned_docs/version-7.1/data-archival/_enable-data-archiving-csharp.mdx b/versioned_docs/version-7.1/data-archival/_enable-data-archiving-csharp.mdx deleted file mode 100644 index 4b2741bca0..0000000000 --- a/versioned_docs/version-7.1/data-archival/_enable-data-archiving-csharp.mdx +++ /dev/null @@ -1,120 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, data archiving is disabled. - To use the archiving feature, you must first **enable** it. - -* When configuring the feature, - you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. - -* Once enabled, the archiving task runs periodically at the configured frequency, - scanning the database for documents that have been scheduled for archival. - Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). - -* In this article: - * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) - * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) - - -## Enable archiving - from the Client API - -Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. -**Example**: - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.Send -store.Maintenance.Send(configureArchivalOp); -`} - - - - -{`// Define the archival configuration object -var configuration = new DataArchivalConfiguration -{ - // Enable archiving - Disabled = false, - - // Optional: override the default archiving frequency - // Scan for documents scheduled for archiving every 180 seconds - ArchiveFrequencyInSec = 180, - - // Optional: limit the number of documents processed in each archival run - MaxItemsToProcess = 100 -}; - -// Define the archival operation, pass the configuration -var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); - -// Execute the operation by passing it to Maintenance.SendAsync -await store.Maintenance.SendAsync(configureArchivalOp); -`} - - - -**Syntax**: - - - -{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) -`} - - - - - -{`public class DataArchivalConfiguration -\{ - public bool Disabled \{ get; set; \} - public long? ArchiveFrequencyInSec \{ get; set; \} - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | -| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | -| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | - - - -## Enable archiving - from the Studio - -![Enable archiving](./assets/enable-archiving.png) - -1. Go to **Settings > Data Archival**. -2. Toggle on to enable data archival. -3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. - Default is 60 seconds. -4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. -5. Click Save to apply your settings. - - - - diff --git a/versioned_docs/version-7.1/data-archival/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-7.1/data-archival/_schedule-document-archiving-csharp.mdx deleted file mode 100644 index cd81710280..0000000000 --- a/versioned_docs/version-7.1/data-archival/_schedule-document-archiving-csharp.mdx +++ /dev/null @@ -1,274 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Documents cannot be archived directly - they must be scheduled for archival. - To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). - This can be done in several ways, as described in this article. - -* **Note**: - Just scheduling a document for archival does Not archive it at the specified time. - Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). - This task periodically scans the database for documents scheduled for archival. - The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). - -* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. - The `@archive-at` metadata property will then be replaced with `@archived: true`. - -* You can schedule documents for archival even if the archiving feature is not yet enabled. - These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. -* In this article: - * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) - * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) - * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) - * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) - - -## Schedule a SINGLE document for archiving - from the Client API - -To schedule a single document for archival from the Client API, -add the `@archive-at` property directly to the document metadata as follows: - - - - -{`using (var session = store.OpenSession()) -{ - // Load the document to schedule for archiving - var company = session.Load("companies/91-A"); - - // Access the document's metadata - var metadata = session.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - session.SaveChanges(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - // Load the document to schedule for archiving - var company = await asyncSession.LoadAsync("companies/91-A"); - - // Access the document's metadata - var metadata = asyncSession.Advanced.GetMetadataFor(company); - - // Set the future archival date (in UTC) - var archiveDate = SystemTime.UtcNow.AddDays(1); - metadata["@archive-at"] = archiveDate; - - // Save the changes - await asyncSession.SaveChangesAsync(); -} -`} - - - - -Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - - - -## Schedule a SINGLE document for archiving - from the Studio - -* To schedule a single document for archival from the Studio: - * Open the Document view. - * Add the `@archive-at` property to the document's metadata. - * Set its value to the desired archive time in UTC format. - * Save the document. - -![Schedule a document for archiving](./assets/schedule-document-for-archiving.png) - -1. This is the `@archive-at` property that was added to the document's metadata. - E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` -2. After saving the document, the Studio displays the time remaining until the document is archived. - - - -## Schedule MULTIPLE documents for archiving - from the Client API - -* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. - -* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. - In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). - -* When the patch operation is executed, - the server will add the `@archive-at` property to the metadata of all documents that match the query filter. -**Example:** - -The following example schedules all orders that were made at least a year ago for archival. -The **patch query** filters for these older orders. -Any document matching the query is then scheduled for archival by the **patch script**. - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - // The patch query: - // ================ - from Orders - where OrderedAt < '{oldDateString}' - update {{ - // The patch script - schedule for archival: - // ========================================= - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch query string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < '{oldDateString}' - update {{ - archived.archiveAt(this, '{archiveDateString}') - }}"; - -// Define the patch operation, pass the patch query string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`var archiveDate = SystemTime.UtcNow.AddDays(1); -string archiveDateString = archiveDate.ToString("o"); - -var oldDate = SystemTime.UtcNow.AddYears(-1); -string oldDateString = oldDate.ToString("o"); - -// Define the patch string -// Request to archive all Orders older than one year -string patchByQuery = $@" - from Orders - where OrderedAt < $p0 - update {{ - archived.archiveAt(this, $p1) - }}"; - -// Define the patch operation, pass the patch query -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery, - QueryParameters = new Parameters() - { - { "p0", oldDateString }, - { "p1", archiveDateString } - } -}); - -// Execute the operation by passing it to Operations.SendAsync -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.archiveAt(doc, utcDateTimeString) -`} - - - -| Parameter | Type | Description | -|-----------------------|-------------|--------------------------------------------------------------------------------------| -| **doc** | `object` | The document to schedule for archiving. | -| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | - -To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). - - - -## Schedule MULTIPLE documents for archiving - from the Studio - -* To schedule multiple documents for archiving from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. - -![Schedule multiple documents for archiving](./assets/schedule-multiple-documents-for-archiving.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - - diff --git a/versioned_docs/version-7.1/data-archival/_unarchiving-documents-csharp.mdx b/versioned_docs/version-7.1/data-archival/_unarchiving-documents-csharp.mdx deleted file mode 100644 index 1f12e49710..0000000000 --- a/versioned_docs/version-7.1/data-archival/_unarchiving-documents-csharp.mdx +++ /dev/null @@ -1,230 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Archived documents can be unarchived at any time. - -* The archiving feature does Not need to be enabled to unarchive documents. - Any previously archived document can be unarchived, regardless of the feature's current state. - -* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. - This will not clear the internal archived status of the document. - To properly unarchive a document, use the `archived.unarchive()` method as described below. - -* In this article: - * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) - * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) - * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) - - -## Unarchive documents - from the Client API - -* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, - which targets one or more documents based on the patch query. - -* You can apply any filtering condition within the query to target only the documents you want to unarchive. - -* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents - that match the **patch query**. -**Example:** - -The following operation will unarchive ALL archived documents in the _Orders_ collection. - - - - -{`// Define the patch query string -string patchByQuery = @" - // The patch query: - // ================ - from Orders - update - { - // The patch script: - // ================= - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -store.Operations.Send(patchByQueryOp); -`} - - - - -{`// Define the patch query string -string patchByQuery = @" - from Orders - update - { - archived.unarchive(this) - }"; - -// Define the patch operation, pass the patch string -var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() -{ - Query = patchByQuery -}); - -// Execute the operation by passing it to Operations.Send -await store.Operations.SendAsync(patchByQueryOp); -`} - - - -**Syntax:** - - - -{`archived.unarchive(doc) -`} - - - -| Parameter | Type | Description | -|------------|----------|----------------------------| -| **doc** | `object` | The document to unarchive. | - - - -## Unarchive documents - from the Studio - -* To unarchive documents from the Studio: - * Open the Patch view. - * Enter a patch script that uses the `archived.unarchive()` method. - * Execute the patch. -**Example**: - -The following patch script, used directly in the Studio, -performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. -It will unarchive all archived documents in the _Orders_ collection. - -![Unarchive documents](./assets/unarchive-documents.png) - -1. Open the Patch view. -2. Enter the patch script. -3. Click to execute the patch. -4. You can test the patch on a sample document before executing the whole operation. - Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). - - - -## Unarchiving documents with index-based patch queries - -* When running a patch query to unarchive documents over an index, - you need to consider the index configuration regarding archived documents. - -* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - - because those documents are not included in the index. - As a result, no documents will be unarchived by the patch operation. - -* For example, the following patch query uses a dynamic query that creates an auto-index. - If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, - then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - - and the patch operation will not unarchive any documents. - - - -{`string patchByQuery = @" - // This filtering query creates an auto-index: - // =========================================== - from Orders - where ShipTo.Country == 'USA' - update - \{ - archived.unarchive(this) - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - -Two possible workarounds are: - -1. **Configure the index to include archived documents**: - This ensures archived documents are included in the index and can be matched by the patch query. - Use this option only if including archived documents in the index aligns with your indexing strategy. - - **For auto-indexes**: - Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. - **For static-indexes**: - Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, - or - configure the definition of the specific static-index to include archived documents. - See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). - -2. **Use a collection query instead of an index query**: - Run a simple collection-based query that does not rely on an index. - Apply your filtering logic inside the patch script to unarchive only the relevant documents. - - For example: - - -{`string patchByQuery = @" - // Perform a collection query: - // =========================== - from Orders as order - update - \{ - // Filter documents inside the script: - // =================================== - if (order.ShipTo.City == 'New York') - \{ - archived.unarchive(this) - \} - \}"; - -var patchByQueryOp = new PatchByQueryOperation(patchByQuery); -store.Operations.Send(patchByQueryOp); -`} - - - - - - diff --git a/versioned_docs/version-7.1/data-archival/archived-documents-and-other-features.mdx b/versioned_docs/version-7.1/data-archival/archived-documents-and-other-features.mdx index 6cf644a121..6e66d0d452 100644 --- a/versioned_docs/version-7.1/data-archival/archived-documents-and-other-features.mdx +++ b/versioned_docs/version-7.1/data-archival/archived-documents-and-other-features.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ArchivedDocumentsAndOtherFeaturesCsharp from './_archived-documents-and-other-features-csharp.mdx'; +import ArchivedDocumentsAndOtherFeaturesCsharp from './content/_archived-documents-and-other-features-csharp.mdx'; diff --git a/versioned_docs/version-7.1/data-archival/content/_archived-documents-and-other-features-csharp.mdx b/versioned_docs/version-7.1/data-archival/content/_archived-documents-and-other-features-csharp.mdx new file mode 100644 index 0000000000..c6b348ed92 --- /dev/null +++ b/versioned_docs/version-7.1/data-archival/content/_archived-documents-and-other-features-csharp.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Once you have archived documents in your database (see how to [enable](../data-archival/enable-data-archiving.mdx) and [schedule](../data-archival/schedule-document-archiving.mdx) document archiving), + RavenDB features can detect these documents and handle them in different ways. + +* Some features, like indexes and data subscriptions, provide native support for configuring whether to: + * **Exclude** archived documents from processing, reducing index size and improving query relevance. + * **Include** only archived documents, for tasks that target archived data specifically. + * **Process both** archived and non-archived documents when needed. + +* Other features can manage archived documents differently based on their purpose. For example: + * ETL tasks can skip or selectively process archived documents. + * Archived documents can be included or excluded when exporting or importing data. + +* Limiting processing to either archived or non-archived documents may improve performance by reducing workload and transfer volume. + +* Learn more below about how various RavenDB features interact with archived documents. +* In this article: + * [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing) + * [Archived documents and querying](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-querying) + * [Archived documents and data subscriptions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-subscriptions) + * [Archived documents and document extensions](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-document-extensions) + * [Archived documents and smuggler (export/import)](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-smuggler-(export/import)) + * [Archived documents and expiration](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-expiration) + * [Archived documents and ETL](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-etl) + * [Archived documents and backup](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-backup) + * [Archived documents and replication](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-replication) + * [Archived documents and patching](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-patching) + + +## Archived documents and indexing + +* Indexing performance may decline as the database grows, since a larger number of documents increases indexing load, expands index size, and can eventually reduce query speed. +* Archiving documents and excluding them from indexing can be an effective way to maintain performance. + By removing low-priority or infrequently accessed documents from the indexing process, RavenDB can create smaller, faster indexes focused on current or high-value data. + This also improves the relevance and responsiveness of queries, as they execute over a smaller and more meaningful dataset. +* **Configuring indexing behavior - Static indexes**: + * **At the database level or server-wide**: + To control whether static indexes process archived documents from the source collection, + set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) + configuration key at either the database level or server-wide (default: `ExcludeArchived`). + * Note that this setting applies only to static-indexes that are using _Documents_ as their data source. + This global configuration does Not apply to static-indexes based on _Time Series_ or _Counters_, which default to `IncludeArchived`. + * **Per index**: + You can override this global behavior per-index directly in the index definition, using the Client API from the Studio + (see the examples below). + +* **Configuring indexing behavior - Auto indexes:** + * **At the database level or server-wide**: + To control whether auto-indexes process archived documents at the database level or server-wide, + set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key (default `ExcludeArchived`). + * **Per index**: + Unlike static indexes, you cannot configure this behavior per auto-index, + because dynamic queries (which trigger auto-index creation) do not provide a way to control this setting. +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the index. + * `IncludeArchived`: both archived and non-archived documents are processed by the index. + * `ArchivedOnly`: only archived documents are processed by the index. +##### Configuring archived document processing for a static index - from the Client API + +You can configure how a static index handles archived documents when creating the index using the Client API. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`public class Orders_ByOrderDate : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public DateTime OrderDate { get; set; } + } + + public Orders_ByOrderDate() + { + Map = orders => from order in orders + select new IndexEntry + { + OrderDate = order.OrderedAt + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByOrderDate_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByOrderDate_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + return { + OrderDate: order.OrderedAt + }; + })" + }; + + // Configure whether the index should process data from archived documents: + // ======================================================================== + ArchivedDataProcessingBehavior = + // Can set the to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinitionBuilder() +{ + Map = orders => from order in orders + select new { order.OrderedAt } +} + .ToIndexDefinition(new DocumentConventions()); + +indexDefinition.Name = "Orders/ByOrderDate"; + +// Configure whether the index should process data from archived documents: +// ======================================================================== +indexDefinition.ArchivedDataProcessingBehavior = + // You can set to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' + ArchivedDataProcessingBehavior.IncludeArchived; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + + +When a static-index is configured to include **both** archived and non-archived documents in its processing, +you can also apply custom logic based on the presence of the `@archived` metadata property. + +For example: + + + + +{`public class Orders_ByArchivedStatus : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public bool? isArchived { get; set; } + public DateTime? OrderDate { get; set; } + public string ShipToCountry { get; set; } + } + + public Orders_ByArchivedStatus() + { + Map = orders => from order in orders + let metadata = MetadataFor(order) + + // Retrieve the '@archived' metadata property from the document: + let archivedProperty = + metadata.Value(Raven.Client.Constants.Documents.Metadata.Archived) + // Alternative syntax: + // let archivedProperty = + // (bool?)metadata[Raven.Client.Constants.Documents.Metadata.Archived] + + select new IndexEntry + { + // Index whether the document is archived: + isArchived = archivedProperty == true, + + // Index the order date only if the document is archived: + OrderDate = archivedProperty == true ? order.OrderedAt : null, + + // Index the destination country only if the document is not archived: + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`public class Orders_ByArchivedStatus_JS : AbstractJavaScriptIndexCreationTask +{ + public Orders_ByArchivedStatus_JS() + { + Maps = new HashSet() + { + @"map('Orders', function (order) { + var metadata = metadataFor(order); + var archivedProperty = metadata['@archived']; + + var isArchived = (archivedProperty === true); + + var orderDate = isArchived ? order.OrderedAt : null; + var shipToCountry = !isArchived ? order.ShipTo.Country : null; + + return { + IsArchived: isArchived, + OrderDate: orderDate, + ShipToCountry: shipToCountry + }; + })" + }; + + ArchivedDataProcessingBehavior = + Raven.Client.Documents.DataArchival.ArchivedDataProcessingBehavior.IncludeArchived; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "Orders/ByArchivedStatus", + + Maps = new HashSet + { + @"from order in docs.Orders + let metadata = MetadataFor(order) + let archivedProperty = (bool?)metadata[""@archived""] + + select new + { + IsArchived = archivedProperty == true, + OrderDate = archivedProperty == true ? order.OrderedAt : null, + ShipToCountry = archivedProperty == null ? order.ShipTo.Country : null + }" + }, + + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.IncludeArchived +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + +##### Configuring archived document processing for a static index - from the Studio + +You can configure how a static index handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key. + +![Configure index](../assets/configure-static-index.png) + +1. Open the [Indexes list view](../studio/database/indexes/indexes-list-view.mdx) and select the index you want to configure, + or create a new index. +2. Scroll down and open the **Archived Data** tab. +3. Click to select how this index should process archived documents: + * **Default**: The index will use the behavior set by the global configuration. + * **Exclude Archived**: Index only non-archived documents. + * **Include Archived**: Index both archived and non-archived documents. + * **Archived Only**: Index only archived documents. + +![Processing options](../assets/processing-options.png) + + + +## Archived documents and querying + +* **Full collection queries**: + * Queries that scan an entire collection without any filtering condition (e.g. `from Orders`) will include archived documents. + * These queries are not influenced by indexing configuration related to archived documents because they do not use indexes. + * Learn more about full collection queries in [Full collection query](../client-api/session/querying/how-to-query.mdx#collectionQuery). + +* **Dynamic queries (auto-indexes)**: + * When making a dynamic query, RavenDB creates an auto-index to serve it. + Whether that index processes archived documents depends on the value of the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key at the time the query is made. + * Once created, the auto-index retains that behavior. + Query results will continue to reflect the configuration that was in effect when the index was first built - even if the setting is changed later. + * Learn more about dynamic queries in [Query a collection - with filtering](../client-api/session/querying/how-to-query.mdx#dynamicQuery). + +* **Querying static-indexes**: + * When querying a static-index, the results will include, exclude, or consist solely of archived documents depending on how the static-index was configured. + The index behavior is determined by: + * the value of the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key at the time the static-index was created, or - + * the explicit setting in the index definition, which overrides the global configuration key. + * The index's archived data processing behavior can be modified after its creation using the Studio or the Client API. + + + +## Archived documents and subscriptions + +* Processing large volumes of documents in data subscriptions increases the workload on both the server and subscription workers. +* You can reduce this load by defining the subscription query to exclude archived documents, include only archived documents, or process both archived and non-archived data. + This gives you control over which documents are sent to workers - helping you focus on the most relevant data and reduce unnecessary processing. +* **Configuring the subscription task behavior**: + * **At the database level or server-wide**: + To control whether queries in data subscription tasks process archived documents, + set the `Subscriptions.ArchivedDataProcessingBehavior` configuration key at either the database level or server-wide + (default: `ExcludeArchived`). + * **Per task**: + You can override this global behavior per data subscription task directly in the task definition, + using the Client API or from the Studio (see the examples below). +* The available configuration options are: + * `ExcludeArchived`: only non-archived documents are processed by the subscription query. + * `IncludeArchived`: both archived and non-archived documents are processed by the subscription query. + * `ArchivedOnly`: only archived documents are processed by the subscription query. +##### Configuring archived document processing for a data subscription task - from the Client API + +You can configure how a subscription task handles archived documents when creating the subscription using the Client API. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + + + +Example: + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + +{`var subscriptionName = store.Subscriptions + .Create(new SubscriptionCreationOptions() +{ + Name = "ArchivedOrdersSubscription", + Query = "from Orders", + // Workers that will subscribe to this subscription task + // will receive only archived documents from the 'Orders' collection. + ArchivedDataProcessingBehavior = ArchivedDataProcessingBehavior.ArchivedOnly + + // You can set the behavior to 'ExcludeArchived', 'IncludeArchived, or 'ArchivedOnly' +}); +`} + + + + + +##### Configuring archived document processing for a data subscription task - from the Studio + +You can configure how a subscription task handles archived documents directly from the Studio. +This setting will **override** the global configuration defined by the [Subscriptions.ArchivedDataProcessingBehavior](../server/configuration/subscription-configuration.mdx#subscriptionsarchiveddataprocessingbehavior) configuration key. + +![Configure subscription](../assets/configure-subscription.png) + +1. Open the [Ongoing tasks list view](../studio/database/tasks/ongoing-tasks/general-info.mdx) and select the subscription task you want to configure, + or create a new subscription. +2. Click to select how the subscription query should process archived documents: + * **Default**: The subscription will use the behavior set by the global configuration. + * **Exclude Archived**: Process only non-archived documents. + * **Include Archived**: Process both archived and non-archived documents. + * **Archived Only**: Process only archived documents. + + + +## Archived documents and document extensions + +* **Attachments**: + * Attachments are Not archived (compressed), even if the document they belong to is archived. + +* **Counters**: + * Counters are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Counters_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Time series**: + * Time series are Not archived (compressed), even if the document they belong to is archived. + * Unlike indexes whose source data is _Documents_ - which default to `ExcludeArchived` - + indexes whose source data is _Time series_ do process archived documents by default (`IncludeArchived`). + This behavior can be modified in the index definition. + +* **Revisions**: + * No revision is created at the time the server archives a document, even if the Revisions feature is enabled. + * However, if you modify an archived document (when Revisions are enabled), a revision is created for that document - and that revision is archived as well. + + + +## Archived documents and smuggler (export/import) + +You can control whether archived documents are included when exporting or importing a database. +##### Export/Import archived documents - from the Client API + +[Smuggler](../client-api/smuggler/what-is-smuggler.mdx), RavenDB’s tool for database export and import, can be configured to include or exclude archived documents. +By default, archived documents are **included** in the operation. + + + +In this example, exported data **excludes** archived documents: + + + +{`var exportOperation = store.Smuggler.ExportAsync( + new DatabaseSmugglerExportOptions() + \{ + // Export only non-archived documents: + IncludeArchived = false + \}, "DestinationFilePath"); +`} + + + + + + + +In this example, imported data **includes** archived documents: + + + +{`var importOperation = store.Smuggler.ImportAsync( + new DatabaseSmugglerImportOptions() + \{ + // Include archived documents in the import: + IncludeArchived = true + \}, "SourceFilePath"); +`} + + + + +##### Export archived documents - from the Studio + +![Export archived documents](../assets/export-archived-documents.png) + +1. Go to **Tasks > Export Database**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the database export. +##### Import archived documents - from the Studio + +![Import archived documents](../assets/import-archived-documents.png) + +1. Go to **Tasks > Import Data**. +2. Toggle the **Include archived documents** option to control whether archived documents are included in the import. + + + +## Archived documents and expiration + +* Archiving can be used alongside other features, such as [Document expiration](../server/extensions/expiration.mdx). + +* For example, a document can be scheduled to be archived after six months and expired after one year. + This allows you to keep recent documents active and quickly accessible, move older documents to archival storage where slower access is acceptable, + and eventually remove documents that are no longer needed. + +* In the following example, both the `@archive-at` and the `@expires` metadata properties have been added to document `companies/90-A` + to schedule it for archiving and expiration, respectively: + + + +{`\{ + "Name": "Wilman Kala", + "Phone": "90-224 8858", + ... + "@metadata": \{ + "@archive-at": "2026-01-06T22:45:30.018Z", + "@expires": "2026-07-06T22:45:30.018Z", + "@collection": "Companies", + ... + \} +\} +`} + + + + + +## Archived documents and ETL + +* An ETL transformation script can examine each source document’s [metadata](../server/ongoing-tasks/etl/raven.mdx#accessing-metadata) + for the existence of the `@archived: true` property, which indicates that the document is archived. + Based on this check, the script can decide how to handle the document - for example, skip it entirely or send only selected fields. + +* With [RavenDB ETL](../server/ongoing-tasks/etl/raven), documents that are archived in the source database and sent to the target + are not archived in the destination database. + +* In the following example, the ETL script checks whether the document is archived, and skips it if it is: + + + +{`var isArchived = this['@metadata']['@archived']; + +if (isArchived === true) \{ + return; // Do not process archived documents +\} + +// Transfer only non-archived documents to the target +loadToOrders(this); +`} + + + + + +## Archived documents and backup + +* Archived documents are included in database backups (both _logical backups_ and _snapshots_), + no special configuration is required. + +* When restoring a database from a backup, archived documents are restored as well, + and their archived status is preserved. + + + +## Archived documents and replication + +Archived documents are included in [Internal](../server/clustering/replication/replication-overview.mdx#internal-replication) replication, +[External](../server/clustering/replication/replication-overview.mdx#external-replication) replication, and [Hub/Sink](../server/clustering/replication/replication-overview.mdx#hubsink-replication) replication - +no special configuration is required. + + + +## Archived documents and patching + +* Patching can be used to **schedule** multiple documents for archiving. See the dedicated sections: + [Schedule multiple documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio). + [Schedule multiple documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). + +* Patching is used to **unarchive** documents. + See the dedicated article [Unarchiving documents](../data-archival/unarchiving-documents.mdx). + +* When **cloning** an archived document using the `put` method within a patching script + (see this [clone document example](../client-api/operations/patching/single-document.mdx#clone-document)) the cloned document will Not be archived, + and the `@archived: true` property will be removed from the cloned document. + + + + diff --git a/versioned_docs/version-7.1/data-archival/content/_enable-data-archiving-csharp.mdx b/versioned_docs/version-7.1/data-archival/content/_enable-data-archiving-csharp.mdx new file mode 100644 index 0000000000..cdcdfecd0f --- /dev/null +++ b/versioned_docs/version-7.1/data-archival/content/_enable-data-archiving-csharp.mdx @@ -0,0 +1,120 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, data archiving is disabled. + To use the archiving feature, you must first **enable** it. + +* When configuring the feature, + you can also set the **frequency** at which RavenDB scans the database for documents scheduled for archiving. + +* Once enabled, the archiving task runs periodically at the configured frequency, + scanning the database for documents that have been scheduled for archival. + Learn how to schedule documents for archival in [Schedule document archiving](../data-archival/schedule-document-archiving.mdx). + +* In this article: + * [Enable archiving - from the Client API](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-client-api) + * [Enable archiving - from the Studio](../data-archival/enable-data-archiving.mdx#enable-archiving---from-the-studio) + + +## Enable archiving - from the Client API + +Use `ConfigureDataArchivalOperation` to enable archiving for the database and configure the archiving task. +**Example**: + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.Send +store.Maintenance.Send(configureArchivalOp); +`} + + + + +{`// Define the archival configuration object +var configuration = new DataArchivalConfiguration +{ + // Enable archiving + Disabled = false, + + // Optional: override the default archiving frequency + // Scan for documents scheduled for archiving every 180 seconds + ArchiveFrequencyInSec = 180, + + // Optional: limit the number of documents processed in each archival run + MaxItemsToProcess = 100 +}; + +// Define the archival operation, pass the configuration +var configureArchivalOp = new ConfigureDataArchivalOperation(configuration); + +// Execute the operation by passing it to Maintenance.SendAsync +await store.Maintenance.SendAsync(configureArchivalOp); +`} + + + +**Syntax**: + + + +{`public ConfigureDataArchivalOperation(DataArchivalConfiguration configuration) +`} + + + + + +{`public class DataArchivalConfiguration +\{ + public bool Disabled \{ get; set; \} + public long? ArchiveFrequencyInSec \{ get; set; \} + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Disabled** | `bool` | `true` - archiving is disabled for the entire database (default).
`false` - archiving is enabled for the database. | +| **ArchiveFrequencyInSec** | `long?` | Frequency (in seconds) at which the server scans for documents scheduled for archiving. Default: `60` | +| **MaxItemsToProcess** | `long?` | The maximum number of documents the archiving task will process in a single run (i.e., each time it is triggered by the configured frequency). Default: `int.MaxValue` | + + + +## Enable archiving - from the Studio + +![Enable archiving](../assets/enable-archiving.png) + +1. Go to **Settings > Data Archival**. +2. Toggle on to enable data archival. +3. Toggle on to customize the frequency at which the server scans for documents scheduled for archiving. + Default is 60 seconds. +4. Toggle on to customize the maximum number of documents the archiving task will process in a single run. +5. Click Save to apply your settings. + + + + diff --git a/versioned_docs/version-7.1/data-archival/content/_schedule-document-archiving-csharp.mdx b/versioned_docs/version-7.1/data-archival/content/_schedule-document-archiving-csharp.mdx new file mode 100644 index 0000000000..0414d08e3f --- /dev/null +++ b/versioned_docs/version-7.1/data-archival/content/_schedule-document-archiving-csharp.mdx @@ -0,0 +1,274 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Documents cannot be archived directly - they must be scheduled for archival. + To **schedule a document** for archival, add the `@archive-at` property to the document's metadata and set its value to the desired archival time (in UTC). + This can be done in several ways, as described in this article. + +* **Note**: + Just scheduling a document for archival does Not archive it at the specified time. + Actual archiving is performed only by a background task that runs when the archival feature is [enabled](../data-archival/enable-data-archiving.mdx). + This task periodically scans the database for documents scheduled for archival. + The scan frequency is configurable when [enabling ](../data-archival/enable-data-archiving.mdx) the archival feature (default: 60 seconds). + +* The archiving task will archive any document whose `@archive-at` time has passed at the time of the scan. + The `@archive-at` metadata property will then be replaced with `@archived: true`. + +* You can schedule documents for archival even if the archiving feature is not yet enabled. + These documents will be archived once the feature is enabled and the task runs - provided the scheduled time has already passed. +* In this article: + * [Schedule a SINGLE document for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-client-api) + * [Schedule a SINGLE document for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-a-single-document-for-archiving---from-the-studio) + * [Schedule MULTIPLE documents for archiving - from the Client API](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) + * [Schedule MULTIPLE documents for archiving - from the Studio](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-studio) + + +## Schedule a SINGLE document for archiving - from the Client API + +To schedule a single document for archival from the Client API, +add the `@archive-at` property directly to the document metadata as follows: + + + + +{`using (var session = store.OpenSession()) +{ + // Load the document to schedule for archiving + var company = session.Load("companies/91-A"); + + // Access the document's metadata + var metadata = session.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + session.SaveChanges(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + // Load the document to schedule for archiving + var company = await asyncSession.LoadAsync("companies/91-A"); + + // Access the document's metadata + var metadata = asyncSession.Advanced.GetMetadataFor(company); + + // Set the future archival date (in UTC) + var archiveDate = SystemTime.UtcNow.AddDays(1); + metadata["@archive-at"] = archiveDate; + + // Save the changes + await asyncSession.SaveChangesAsync(); +} +`} + + + + +Learn more about modifying the metadata of a document in [Modifying Document Metadata](../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + + + +## Schedule a SINGLE document for archiving - from the Studio + +* To schedule a single document for archival from the Studio: + * Open the Document view. + * Add the `@archive-at` property to the document's metadata. + * Set its value to the desired archive time in UTC format. + * Save the document. + +![Schedule a document for archiving](../assets/schedule-document-for-archiving.png) + +1. This is the `@archive-at` property that was added to the document's metadata. + E.g.: `"@archive-at": "2025-06-25T14:00:00.0000000Z"` +2. After saving the document, the Studio displays the time remaining until the document is archived. + + + +## Schedule MULTIPLE documents for archiving - from the Client API + +* Use the `PatchByQueryOperation` to schedule multiple documents for archiving. + +* In the **patch query**, you can apply any filtering condition to select only the documents you want to archive. + In the **patch script**, call the `archived.archiveAt` method to set the desired archival time (in UTC). + +* When the patch operation is executed, + the server will add the `@archive-at` property to the metadata of all documents that match the query filter. +**Example:** + +The following example schedules all orders that were made at least a year ago for archival. +The **patch query** filters for these older orders. +Any document matching the query is then scheduled for archival by the **patch script**. + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + // The patch query: + // ================ + from Orders + where OrderedAt < '{oldDateString}' + update {{ + // The patch script - schedule for archival: + // ========================================= + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch query string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < '{oldDateString}' + update {{ + archived.archiveAt(this, '{archiveDateString}') + }}"; + +// Define the patch operation, pass the patch query string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`var archiveDate = SystemTime.UtcNow.AddDays(1); +string archiveDateString = archiveDate.ToString("o"); + +var oldDate = SystemTime.UtcNow.AddYears(-1); +string oldDateString = oldDate.ToString("o"); + +// Define the patch string +// Request to archive all Orders older than one year +string patchByQuery = $@" + from Orders + where OrderedAt < $p0 + update {{ + archived.archiveAt(this, $p1) + }}"; + +// Define the patch operation, pass the patch query +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery, + QueryParameters = new Parameters() + { + { "p0", oldDateString }, + { "p1", archiveDateString } + } +}); + +// Execute the operation by passing it to Operations.SendAsync +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.archiveAt(doc, utcDateTimeString) +`} + + + +| Parameter | Type | Description | +|-----------------------|-------------|--------------------------------------------------------------------------------------| +| **doc** | `object` | The document to schedule for archiving. | +| **utcDateTimeString** | `string` | The UTC timestamp (as a string) that specifies when the document should be archived. | + +To learn more about the `PatchByQueryOperation`, see [Set-based patch operations](../client-api/operations/patching/set-based.mdx). + + + +## Schedule MULTIPLE documents for archiving - from the Studio + +* To schedule multiple documents for archiving from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.archiveAt` method, providing the desired archive date in UTC. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api) shown above. + +![Schedule multiple documents for archiving](../assets/schedule-multiple-documents-for-archiving.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + + diff --git a/versioned_docs/version-7.1/data-archival/content/_unarchiving-documents-csharp.mdx b/versioned_docs/version-7.1/data-archival/content/_unarchiving-documents-csharp.mdx new file mode 100644 index 0000000000..faac23a4e8 --- /dev/null +++ b/versioned_docs/version-7.1/data-archival/content/_unarchiving-documents-csharp.mdx @@ -0,0 +1,230 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Archived documents can be unarchived at any time. + +* The archiving feature does Not need to be enabled to unarchive documents. + Any previously archived document can be unarchived, regardless of the feature's current state. + +* Do **not** attempt to unarchive a document by manually removing the `@archived: true` metadata property from the document. + This will not clear the internal archived status of the document. + To properly unarchive a document, use the `archived.unarchive()` method as described below. + +* In this article: + * [Unarchive documents - from the Client API](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) + * [Unarchive documents - from the Studio](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-studio) + * [Unarchiving documents with index-based patch queries](../data-archival/unarchiving-documents.mdx#unarchiving-documents-with-index-based-patch-queries) + + +## Unarchive documents - from the Client API + +* To unarchive documents from the Client API, use the `PatchByQueryOperation` operation, + which targets one or more documents based on the patch query. + +* You can apply any filtering condition within the query to target only the documents you want to unarchive. + +* Within the **patch script**, call the `archived.unarchive()` method to unarchive all documents + that match the **patch query**. +**Example:** + +The following operation will unarchive ALL archived documents in the _Orders_ collection. + + + + +{`// Define the patch query string +string patchByQuery = @" + // The patch query: + // ================ + from Orders + update + { + // The patch script: + // ================= + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +store.Operations.Send(patchByQueryOp); +`} + + + + +{`// Define the patch query string +string patchByQuery = @" + from Orders + update + { + archived.unarchive(this) + }"; + +// Define the patch operation, pass the patch string +var patchByQueryOp = new PatchByQueryOperation(new IndexQuery() +{ + Query = patchByQuery +}); + +// Execute the operation by passing it to Operations.Send +await store.Operations.SendAsync(patchByQueryOp); +`} + + + +**Syntax:** + + + +{`archived.unarchive(doc) +`} + + + +| Parameter | Type | Description | +|------------|----------|----------------------------| +| **doc** | `object` | The document to unarchive. | + + + +## Unarchive documents - from the Studio + +* To unarchive documents from the Studio: + * Open the Patch view. + * Enter a patch script that uses the `archived.unarchive()` method. + * Execute the patch. +**Example**: + +The following patch script, used directly in the Studio, +performs the same operation as the [Client API example](../data-archival/unarchiving-documents.mdx#unarchive-documents---from-the-client-api) shown above. +It will unarchive all archived documents in the _Orders_ collection. + +![Unarchive documents](../assets/unarchive-documents.png) + +1. Open the Patch view. +2. Enter the patch script. +3. Click to execute the patch. +4. You can test the patch on a sample document before executing the whole operation. + Learn more in [Test patch](../studio/database/documents/patch-view.mdx#test-patch). + + + +## Unarchiving documents with index-based patch queries + +* When running a patch query to unarchive documents over an index, + you need to consider the index configuration regarding archived documents. + +* If the index is configured to exclude archived documents, the query portion of the patch operation will not match any archived documents - + because those documents are not included in the index. + As a result, no documents will be unarchived by the patch operation. + +* For example, the following patch query uses a dynamic query that creates an auto-index. + If the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key is set to its default `ExcludeArchived` value, + then even if archived documents exist in the _Orders_ collection with `ShipTo.Country == 'USA'`, they will not be matched - because the auto-index does not include them - + and the patch operation will not unarchive any documents. + + + +{`string patchByQuery = @" + // This filtering query creates an auto-index: + // =========================================== + from Orders + where ShipTo.Country == 'USA' + update + \{ + archived.unarchive(this) + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + +Two possible workarounds are: + +1. **Configure the index to include archived documents**: + This ensures archived documents are included in the index and can be matched by the patch query. + Use this option only if including archived documents in the index aligns with your indexing strategy. + + **For auto-indexes**: + Set the [Indexing.Auto.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingautoarchiveddataprocessingbehavior) configuration key to `IncludeArchived`. + **For static-indexes**: + Set the [Indexing.Static.ArchivedDataProcessingBehavior](../server/configuration/indexing-configuration.mdx#indexingstaticarchiveddataprocessingbehavior) configuration key to `IncludeArchived`, + or - configure the definition of the specific static-index to include archived documents. + See [Archived documents and indexing](../data-archival/archived-documents-and-other-features.mdx#archived-documents-and-indexing). + +2. **Use a collection query instead of an index query**: + Run a simple collection-based query that does not rely on an index. + Apply your filtering logic inside the patch script to unarchive only the relevant documents. + + For example: + + +{`string patchByQuery = @" + // Perform a collection query: + // =========================== + from Orders as order + update + \{ + // Filter documents inside the script: + // =================================== + if (order.ShipTo.City == 'New York') + \{ + archived.unarchive(this) + \} + \}"; + +var patchByQueryOp = new PatchByQueryOperation(patchByQuery); +store.Operations.Send(patchByQueryOp); +`} + + + + + + diff --git a/versioned_docs/version-7.1/data-archival/enable-data-archiving.mdx b/versioned_docs/version-7.1/data-archival/enable-data-archiving.mdx index 5792991f3d..8b1d5eb068 100644 --- a/versioned_docs/version-7.1/data-archival/enable-data-archiving.mdx +++ b/versioned_docs/version-7.1/data-archival/enable-data-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EnableDataArchivingCsharp from './_enable-data-archiving-csharp.mdx'; +import EnableDataArchivingCsharp from './content/_enable-data-archiving-csharp.mdx'; diff --git a/versioned_docs/version-7.1/data-archival/schedule-document-archiving.mdx b/versioned_docs/version-7.1/data-archival/schedule-document-archiving.mdx index c22e6a21ed..09b032fc17 100644 --- a/versioned_docs/version-7.1/data-archival/schedule-document-archiving.mdx +++ b/versioned_docs/version-7.1/data-archival/schedule-document-archiving.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ScheduleDocumentArchivingCsharp from './_schedule-document-archiving-csharp.mdx'; +import ScheduleDocumentArchivingCsharp from './content/_schedule-document-archiving-csharp.mdx'; diff --git a/versioned_docs/version-7.1/data-archival/unarchiving-documents.mdx b/versioned_docs/version-7.1/data-archival/unarchiving-documents.mdx index 808769d015..89afcf916d 100644 --- a/versioned_docs/version-7.1/data-archival/unarchiving-documents.mdx +++ b/versioned_docs/version-7.1/data-archival/unarchiving-documents.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UnarchivingDocumentsCsharp from './_unarchiving-documents-csharp.mdx'; +import UnarchivingDocumentsCsharp from './content/_unarchiving-documents-csharp.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/bulk-insert.mdx b/versioned_docs/version-7.1/document-extensions/attachments/bulk-insert.mdx index c763b6a3ca..296538d2fa 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/bulk-insert.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/bulk-insert.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BulkInsertCsharp from './_bulk-insert-csharp.mdx'; -import BulkInsertPython from './_bulk-insert-python.mdx'; -import BulkInsertNodejs from './_bulk-insert-nodejs.mdx'; +import BulkInsertCsharp from './content/_bulk-insert-csharp.mdx'; +import BulkInsertPython from './content/_bulk-insert-python.mdx'; +import BulkInsertNodejs from './content/_bulk-insert-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_bulk-insert-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_bulk-insert-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-php.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-php.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_copying-moving-renaming-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_copying-moving-renaming-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_deleting-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_deleting-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_deleting-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_deleting-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_deleting-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_deleting-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_deleting-php.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_deleting-php.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_deleting-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_deleting-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_deleting-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_indexing-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_indexing-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_indexing-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_indexing-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_indexing-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_indexing-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_indexing-php.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_indexing-php.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_indexing-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_indexing-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_loading-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_loading-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_loading-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_loading-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_loading-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_loading-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_loading-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_loading-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_loading-php.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_loading-php.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_loading-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_loading-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_loading-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_loading-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_storing-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_storing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_storing-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_storing-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_storing-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_storing-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_storing-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_storing-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_storing-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_storing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_storing-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_storing-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_storing-php.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_storing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_storing-php.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_storing-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_storing-python.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_storing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_storing-python.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_storing-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-csharp.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-java.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-java.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/attachments/_what-are-attachments-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/attachments/content/_what-are-attachments-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/attachments/copying-moving-renaming.mdx b/versioned_docs/version-7.1/document-extensions/attachments/copying-moving-renaming.mdx index 5d9756c7ff..dd66ad7797 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/copying-moving-renaming.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/copying-moving-renaming.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyingMovingRenamingCsharp from './_copying-moving-renaming-csharp.mdx'; -import CopyingMovingRenamingJava from './_copying-moving-renaming-java.mdx'; -import CopyingMovingRenamingPython from './_copying-moving-renaming-python.mdx'; -import CopyingMovingRenamingPhp from './_copying-moving-renaming-php.mdx'; -import CopyingMovingRenamingNodejs from './_copying-moving-renaming-nodejs.mdx'; +import CopyingMovingRenamingCsharp from './content/_copying-moving-renaming-csharp.mdx'; +import CopyingMovingRenamingJava from './content/_copying-moving-renaming-java.mdx'; +import CopyingMovingRenamingPython from './content/_copying-moving-renaming-python.mdx'; +import CopyingMovingRenamingPhp from './content/_copying-moving-renaming-php.mdx'; +import CopyingMovingRenamingNodejs from './content/_copying-moving-renaming-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/deleting.mdx b/versioned_docs/version-7.1/document-extensions/attachments/deleting.mdx index 412aa66a67..604c4058e7 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/deleting.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/deleting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeletingCsharp from './_deleting-csharp.mdx'; -import DeletingJava from './_deleting-java.mdx'; -import DeletingPython from './_deleting-python.mdx'; -import DeletingPhp from './_deleting-php.mdx'; -import DeletingNodejs from './_deleting-nodejs.mdx'; +import DeletingCsharp from './content/_deleting-csharp.mdx'; +import DeletingJava from './content/_deleting-java.mdx'; +import DeletingPython from './content/_deleting-python.mdx'; +import DeletingPhp from './content/_deleting-php.mdx'; +import DeletingNodejs from './content/_deleting-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/indexing.mdx b/versioned_docs/version-7.1/document-extensions/attachments/indexing.mdx index d49e97610c..8fca84b22e 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/indexing.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/loading.mdx b/versioned_docs/version-7.1/document-extensions/attachments/loading.mdx index b845db6865..6c82d701c2 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/loading.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/storing.mdx b/versioned_docs/version-7.1/document-extensions/attachments/storing.mdx index 5e877c3b82..cb3e3b93d1 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/storing.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/storing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringCsharp from './_storing-csharp.mdx'; -import StoringJava from './_storing-java.mdx'; -import StoringPython from './_storing-python.mdx'; -import StoringPhp from './_storing-php.mdx'; -import StoringNodejs from './_storing-nodejs.mdx'; +import StoringCsharp from './content/_storing-csharp.mdx'; +import StoringJava from './content/_storing-java.mdx'; +import StoringPython from './content/_storing-python.mdx'; +import StoringPhp from './content/_storing-php.mdx'; +import StoringNodejs from './content/_storing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/attachments/what-are-attachments.mdx b/versioned_docs/version-7.1/document-extensions/attachments/what-are-attachments.mdx index 1ccc245e7f..d5b7289d6b 100644 --- a/versioned_docs/version-7.1/document-extensions/attachments/what-are-attachments.mdx +++ b/versioned_docs/version-7.1/document-extensions/attachments/what-are-attachments.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreAttachmentsCsharp from './_what-are-attachments-csharp.mdx'; -import WhatAreAttachmentsJava from './_what-are-attachments-java.mdx'; -import WhatAreAttachmentsNodejs from './_what-are-attachments-nodejs.mdx'; +import WhatAreAttachmentsCsharp from './content/_what-are-attachments-csharp.mdx'; +import WhatAreAttachmentsJava from './content/_what-are-attachments-java.mdx'; +import WhatAreAttachmentsNodejs from './content/_what-are-attachments-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_counters-and-other-features-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_counters-and-other-features-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_create-or-modify-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_create-or-modify-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_delete-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_delete-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_delete-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_delete-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_delete-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_delete-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_delete-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_delete-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_delete-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_delete-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_delete-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_delete-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_delete-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_delete-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_including-counters-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_including-counters-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_including-counters-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_including-counters-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_including-counters-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_including-counters-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_including-counters-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_including-counters-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_including-counters-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_including-counters-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_including-counters-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_indexing-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_indexing-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_indexing-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_indexing-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_indexing-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_indexing-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_indexing-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_indexing-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_indexing-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_indexing-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_indexing-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_indexing-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_overview-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_overview-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_overview-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_overview-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_overview-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_overview-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_overview-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_overview-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_overview-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_overview-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_overview-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-csharp.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-java.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-java.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-php.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-php.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-python.mdx b/versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/counters/_retrieve-counter-values-python.mdx rename to versioned_docs/version-7.1/document-extensions/counters/content/_retrieve-counter-values-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/counters/counters-and-other-features.mdx b/versioned_docs/version-7.1/document-extensions/counters/counters-and-other-features.mdx index d6add07485..e41eacaabd 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/counters-and-other-features.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/counters-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersAndOtherFeaturesCsharp from './_counters-and-other-features-csharp.mdx'; -import CountersAndOtherFeaturesJava from './_counters-and-other-features-java.mdx'; -import CountersAndOtherFeaturesPython from './_counters-and-other-features-python.mdx'; -import CountersAndOtherFeaturesPhp from './_counters-and-other-features-php.mdx'; -import CountersAndOtherFeaturesNodejs from './_counters-and-other-features-nodejs.mdx'; +import CountersAndOtherFeaturesCsharp from './content/_counters-and-other-features-csharp.mdx'; +import CountersAndOtherFeaturesJava from './content/_counters-and-other-features-java.mdx'; +import CountersAndOtherFeaturesPython from './content/_counters-and-other-features-python.mdx'; +import CountersAndOtherFeaturesPhp from './content/_counters-and-other-features-php.mdx'; +import CountersAndOtherFeaturesNodejs from './content/_counters-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/create-or-modify.mdx b/versioned_docs/version-7.1/document-extensions/counters/create-or-modify.mdx index 4a3a107910..2d483fd353 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/create-or-modify.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/create-or-modify.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreateOrModifyCsharp from './_create-or-modify-csharp.mdx'; -import CreateOrModifyJava from './_create-or-modify-java.mdx'; -import CreateOrModifyPython from './_create-or-modify-python.mdx'; -import CreateOrModifyPhp from './_create-or-modify-php.mdx'; -import CreateOrModifyNodejs from './_create-or-modify-nodejs.mdx'; +import CreateOrModifyCsharp from './content/_create-or-modify-csharp.mdx'; +import CreateOrModifyJava from './content/_create-or-modify-java.mdx'; +import CreateOrModifyPython from './content/_create-or-modify-python.mdx'; +import CreateOrModifyPhp from './content/_create-or-modify-php.mdx'; +import CreateOrModifyNodejs from './content/_create-or-modify-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/delete.mdx b/versioned_docs/version-7.1/document-extensions/counters/delete.mdx index 17f525f4fa..fdf5cc78c4 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/delete.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/delete.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeleteJava from './_delete-java.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeleteJava from './content/_delete-java.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/including-counters.mdx b/versioned_docs/version-7.1/document-extensions/counters/including-counters.mdx index b3c558ea7f..37133d3a42 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/including-counters.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/including-counters.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCountersCsharp from './_including-counters-csharp.mdx'; -import IncludingCountersJava from './_including-counters-java.mdx'; -import IncludingCountersPython from './_including-counters-python.mdx'; -import IncludingCountersPhp from './_including-counters-php.mdx'; -import IncludingCountersNodejs from './_including-counters-nodejs.mdx'; +import IncludingCountersCsharp from './content/_including-counters-csharp.mdx'; +import IncludingCountersJava from './content/_including-counters-java.mdx'; +import IncludingCountersPython from './content/_including-counters-python.mdx'; +import IncludingCountersPhp from './content/_including-counters-php.mdx'; +import IncludingCountersNodejs from './content/_including-counters-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/indexing.mdx b/versioned_docs/version-7.1/document-extensions/counters/indexing.mdx index 4c38219c5a..9a813d2020 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/indexing.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/indexing.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingJava from './_indexing-java.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingJava from './content/_indexing-java.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/overview.mdx b/versioned_docs/version-7.1/document-extensions/counters/overview.mdx index 3a0db28bdf..567dca58de 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/overview.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/counters/retrieve-counter-values.mdx b/versioned_docs/version-7.1/document-extensions/counters/retrieve-counter-values.mdx index 017ea31775..5d03c0455a 100644 --- a/versioned_docs/version-7.1/document-extensions/counters/retrieve-counter-values.mdx +++ b/versioned_docs/version-7.1/document-extensions/counters/retrieve-counter-values.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RetrieveCounterValuesCsharp from './_retrieve-counter-values-csharp.mdx'; -import RetrieveCounterValuesJava from './_retrieve-counter-values-java.mdx'; -import RetrieveCounterValuesPython from './_retrieve-counter-values-python.mdx'; -import RetrieveCounterValuesPhp from './_retrieve-counter-values-php.mdx'; -import RetrieveCounterValuesNodejs from './_retrieve-counter-values-nodejs.mdx'; +import RetrieveCounterValuesCsharp from './content/_retrieve-counter-values-csharp.mdx'; +import RetrieveCounterValuesJava from './content/_retrieve-counter-values-java.mdx'; +import RetrieveCounterValuesPython from './content/_retrieve-counter-values-python.mdx'; +import RetrieveCounterValuesPhp from './content/_retrieve-counter-values-php.mdx'; +import RetrieveCounterValuesNodejs from './content/_retrieve-counter-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_overview-csharp.mdx deleted file mode 100644 index 0f0c9f41b9..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_overview-csharp.mdx +++ /dev/null @@ -1,327 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, -followed by a call to `SaveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -var company = new Company { - Name = "CompanyName" - }; - -session.Store(company); -companyId = company.Id; -session.SaveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -session.Advanced.Revisions.ForceRevisionCreationFor(company); - -// Call SaveChanges for the revision to be created -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -{`// Force revision creation by ID -// ============================= - -session.Advanced.Revisions.ForceRevisionCreationFor(companyId); -session.SaveChanges(); - -var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; -Assert.Equal(1, revisionsCount); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== - -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -`} - - - -| Parameter | Type | Description | -|--------------|------------------------------|--------------------------------------------------------------------------------------------------| -| **entity** | `T` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | - - - -{`public enum ForceRevisionStrategy -\{ - // Do not force a revision - None, - - // Create a forced revision from the document currently in store - // BEFORE applying any changes made by the user. - // The only exception is for a new document, - // where a revision will be created AFTER the update. - Before -\} -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_overview-nodejs.mdx deleted file mode 100644 index c51d9e1b8f..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_overview-nodejs.mdx +++ /dev/null @@ -1,324 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, -followed by a call to `saveChanges`. - -**Example**: - - - - -{`// Force revision creation by entity -// ================================= - -const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Forcing the creation of a revision by entity can be performed -// only when the entity is tracked, after the document is stored. -await session.advanced.revisions.forceRevisionCreationFor(company); - -// Must call 'saveChanges' for the revision to be created -await session.saveChanges(); - -// Get existing revisions: -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -{`const company = new Company(); -company.name = "CompanyName"; - -const session = documentStore.openSession(); -await session.store(company); -await session.saveChanges(); - -// Force revision creation by ID -const companyId = company.id; -await session.advanced.revisions.forceRevisionCreationFor(companyId); -await session.saveChanges(); - -const revisions = await session.advanced.revisions.getFor(company.id); -const revisionsCount = revisions.length; - -assert.equal(revisionsCount, 1); -`} - - - - -**Syntax**: - - - -{`// Available overloads: -// ==================== -forceRevisionCreationFor(entity); -forceRevisionCreationFor(entity, strategy); -forceRevisionCreationFor(id); -forceRevisionCreationFor(id, strategy); -`} - - - -| Parameter | Type | Description | -|--------------|----------|-------------------------------------------------------------------------------------------------| -| **entity** | `object` | The tracked entity for which you want to create a revision. | -| **id** | `string` | The ID of the document for which you want to create a revision. | -| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | - -**Strategy**: - -`None`: -Do not force a revision - -`Before`: -Create a forced revision from the document currently in store BEFORE applying any changes made by the user. -The only exception is for a new document, where a revision will be created AFTER the update. - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_overview-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_overview-python.mdx deleted file mode 100644 index 8cb585b701..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_overview-python.mdx +++ /dev/null @@ -1,287 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Document Revisions** are snapshots of documents and their extensions: - - * The trail of revisions created for a document can be inspected to track changes made in the document over time. - * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. - - For example, tracking document revisions allows you to check how an employee's contract has changed over time, - restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. - -* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: - - * **Automatic revisions creation**: - When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. - To configure revisions settings, and set limits for the number of revisions retained per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. - - * **Manual revisions creation**: - When revisions settings are disabled, you can still create revisions manually. - See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. -* In this page: - * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) - * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) - * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) - * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) - * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) - * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) - * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) - * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) - * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) - - -## Revisions configuration - -* The revisions configuration enables or disables the creation and purging of revisions for documents, - and optionally limits the number of revisions retained per document. - -* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. - You can modify this behavior and other revisions settings by applying a revisions configuration to the database. - The revisions configuration is stored in the database record. - - - - #### Conflict Revisions - - Revisions created for **conflicting documents** are a special case that is not covered in this article. - - * Conflict revisions are **enabled** by default. - * Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) - * Read about managing conflict revisions via the Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) - - -#### Defining a revisions configuration - -You can apply a revisions configuration using the Studio or the Client API: - -* Via Studio: - * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. - * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. -* Via Client API: - * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. -#### Default settings and collection-specific configurations - -The revisions configuration consists of default settings and/or collection-specific configurations: - -* **Default settings**: - The default settings apply to all documents for which a collection-specific configuration is not defined. - -* **Collection-specific configurations**: - Collection-specific configurations apply only to documents of the collections they are defined for, - overriding the default settings for these collections. - - If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. - -#### Revisions configuration options - -A revisions configuration defines - - -* Whether to enable or disable revisions creation: - * If the revisions configuration is **Enabled** for a collection, - creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, - and optionally the purging of existing revisions for the document. - * If the revisions configuration is **Disabled** for a collection, - RavenDB will **not** automatically create or purge revisions for documents in this collection. - -* Whether to limit the number of revisions that can be kept per document. - RavenDB will only purge revisions if they exceed the limits you set. - -* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). -#### Revisions configuration execution - -Creating a revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - - -1. **Documents are Created, Modified, or Deleted**. - When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. - If the revisions configuration is enabled for this collection: - * A revision of the document will be created. - * Existing revisions will optionally be purged according to the limits set in the configuration. - -2. **Enforce Configuration is applied**. - [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging - according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. - - * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. - Be aware that this operation may require substantial server resources, so time it accordingly. - * Revisions that were created over time but to which no configuration currently applies will be deleted. - Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. - -#### Enabling and disabling revisions for existing documents - -* When revisions creation is **Enabled** for a populated collection: - * The first revision will be created for an existing document the next time the document is modified - (recording the document **after** its modification), or when the document is deleted. - -* When revisions creation is **Disabled** for a collection after revisions have been created: - * The creation of new revisions and the purging of existing revisions will stop. - * Existing revisions will remain intact. - - - -## How it works - -Let's play with revisions a little to get a taste of its advantages. - -1. **Enable Revisions** so we can experiment with the feature. - Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) - or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. - - ![Enable Revisions for the Users Collection](./assets/revisions-1.png) - -2. **Create a new document in the `Users` collection**. - We will follow the automatic creation of revisions for this document. - You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) - or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. - - ![Create a Document](./assets/revisions-2.png) - -3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. - Creating the document also created its first revision. - - ![Revision for Document Creation](./assets/revisions-3.png) - - Click the _"See the current document"_ button to return to the parent document view. - -4. **Modify and Save the document**. - This will create a second revision. - - ![Revision for Document Modification](./assets/revisions-4.png) - -5. **Delete the document**. - Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - including a new revision (called "Delete Revision"), created to indicate that the document was deleted. - - - * A "Delete Revision" is created only if the deleted document has revisions. - * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. - - - To see the revisions created for the document before it was deleted: - * Open the `Documents > Revisions Bin` section in the Studio - * Click the deleted document's ID - - ![Revisions Bin](./assets/revisions-5.png) - -6. **Restore the document**. - Even after a document is deleted, you can still restore it from one of its revisions. - To do so, open the revision containing the content you want to restore. - Click _Clone_ to create a new document from that revision. - - ![Revisions Bin](./assets/revisions-6.png) - - Save the new document using the exact **same ID** as the deleted document. - This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. - - Opening the document’s Revisions Tab will show the full audit trail, - including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. - - ![Restored Revisions](./assets/revisions-7.png) - - - -## Revisions storage - -##### Revisions storage - -When a document revision is created, a full version of the modified document is stored in the revisions storage, -using the same blittable JSON document format as regular documents. -##### Revisions Compression - -* By default, revisions are compressed. - This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. -* At the database level, revisions compression can be customized via the database record, - as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). -* Individual fields are compressed as they are compressed in regular documents: - any text field exceeding 128 bytes is compressed. - Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). -##### Storage of document extensions in revisions - -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - -## Revisions storage - - - -##### Revisions documents storage -* The creation of a document revision stores a full version of the modified document in the revisions storage, - in the same **blittable JSON document** format as that of regular documents. - -* **Revisions compression** - * Revisions are compressed by default. - Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. - * Individual fields are compressed as they are compressed in regular documents: - any text field of more than 128 bytes is compressed. - - - - -##### Revisions document extensions storage -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. - - - - -## Force revision creation - -So far we've discussed the automatic creation of revisions when the feature is enabled. -However, you can also **force the creation** of a document revision, whether the feature is enabled or not. - -This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, -e.g. take a snapshot of the document as a precaution before editing it. - -* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) - or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). -* A revision **will** be created even if the revisions configuration is disabled for the document's collection. -* A revision **will** be created even if the document has not been modified - (unless the document has revisions and the latest revision contains the current document contents). -* Similar to revisions created automatically due to the revisions configuration, - deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), - and a "Delete Revision" will be created. -##### Force revision creation via the Studio - -To create a revision manually via the Studio, -click the **Create Revision** button in the Revisions Tab in the document view. - -![Create a revision manually](./assets/revisions-8.png) -##### Force revision creation via the Client API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. - - - -{`with self.store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" - - session.advanced.revisions.force_revision_creation_for(company) - session.save_changes() - - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) - - self.assertEqual(1, revisions_count) - # Assert revision contains the value 'Before' the changes... - self.assertEqual("HR", revisions[0].name) -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-csharp.mdx deleted file mode 100644 index 1906658a54..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-csharp.mdx +++ /dev/null @@ -1,264 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. -### Extract counters data from revisions: - -Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, -and then extract the counters' data. - - - - -{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = session - .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - -{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' -List revisionsMetadata = await asyncSession - .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); - -// Extract the counters data from the metadata -List countersDataInRevisions = revisionsMetadata - .Where(metadata => - metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) - .Select(metadata => - (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) - .ToList(); -`} - - - - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx deleted file mode 100644 index 266c485b5e..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-nodejs.mdx +++ /dev/null @@ -1,308 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - - - -**Revisions creation** - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing counter. - - - - - -**Stored data** - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - - - - - - -**Reverted data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, - the counters from the revision are restored to functionality along with their values. - - - - - -**Extract counters data from revisions** - -* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, - and then extract the counters' data. - - - -{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' -const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); - -// Extract the counters data from the metadata -const countersDataInRevisions = revisionsMetadata - .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) - .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); -`} - - - - - - - -## Revisions and Time Series - - - -**Revisions Creation** - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). - - - - - -**Stored Data** - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - - - -## Revisions and Attachments - - - -**Revisions Creation** - -* A document revision will be created when: - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. - - - - - -**Stored Data** - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - - - - - - -**Reverted Data** - -* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, - the attachments are restored to their state when the revision was created. - - - - - -## Revisions and Replication - - - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - - - -## Revisions and ETL - - - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - - - -## Revisions and Backup - - - -* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - - - -## Revisions and Data Subscriptions - - - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - - - -## Revisions Import and Export - - - -* Revisions can be imported and exported with a `.ravendbdump` file: - * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) - * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-php.mdx deleted file mode 100644 index 3c8783a8ad..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-php.mdx +++ /dev/null @@ -1,217 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-python.mdx deleted file mode 100644 index d42399f08e..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-python.mdx +++ /dev/null @@ -1,224 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes relationships between Revisions and other RavenDB features, including - - * When is revisions creation triggered by other features - * How revisions are supported by other features - -* In this page: - * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) - * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) - * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) - * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) - * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) - * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) - * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) - * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) - - -## Revisions and Counters - -### Revisions creation: - -* A document revision will be created when: - * A new counter is **created** on the document. - * A counter is **deleted** from the document. - -* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). -### Stored data: - -* A revision that is created for a document that contains counters - will have the `@counters-snapshot` property in its **metadata**. - -* This property holds the counters' names and values at the time when the revision was created. - -* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. - It does not specify the value of the counter on each individual node. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@counters-snapshot": \{ - "counterName1": 7, - "counterName2": 42 - \}, - ... - \} -\} -`} - - -### Reverted data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, -the counters from the revision are restored to functionality along with their values. - - - -## Revisions and Time Series - -### Revisions Creation: - -* A document revision will be created when: - * A new time series is **created** on the document. - * A time series is **deleted** from the document. - (A time series is deleted from a document when all its entries are deleted) - -* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). -### Stored Data: - -* A revision that is created for a document that contains time series - will have the `@timeseries-snapshot` property in its **metadata**. - -* This property does Not hold the time series values data, - it only contains the following information for the time when the revision was created: - * The time series names - * The number of entries in each time series - * Dates of the first and last entry in each time series - -* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@timeseries-snapshot": \{ - "timeSeriesName1": \{ - "Count": 5, - "Start": "2023-03-22T11:25:00.9110000Z", - "End": "2023-03-22T11:28:34.9110000Z" - \}, - "timeSeriesName2": \{ - "Count": 10, - "Start": "2023-03-22T11:26:00.3950000Z", - "End": "2023-03-22T11:28:48.3950000Z" - \} - \}, - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: - -* If the current document **contains** a time series name as in the revision: - * The reverted document will keep the time series entries & values as it was in the current document. - * Time series entries and values from the revision are Not restored. - -* If the current document **doesn't contain** a time series name as in the revision, - or if the document itself was deleted: - * The reverted document will have the time series from the revision - * However, the entries count will be 0 - - - -## Revisions and Attachments - -### Revisions Creation: - -A document revision will be created when: - - * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. - * An attachment is **deleted** from the document. -### Stored Data: - -* A revision that is created for a document with attachments - will have the `@attachments` property in its **metadata**. - -* This property does Not hold the actual attachments, as the files are stored in **separate storage**. - The property only contains the following information for each attachment the document had when the revision was created: - * Attachment file name - * File content type - * File size - * A hash string (a reference to the file in the storage) - -* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. - -* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. - -* Sample revision metadata: - - -{`\{ - ... - "@metadata": \{ - "@attachments": [ - \{ - "Name": "attachmentFileName.png", - "ContentType": "image/png", - "Size": 33241, - "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", - \}, - ], - ... - \} -\} -`} - - -### Reverted Data: - -When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, -the attachments are restored to their state when the revision was created. - - - -## Revisions and Replication - -* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. - -* The revisions will be replicated by all replication types: - * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) - * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) - * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) - -* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). - - - -## Revisions and ETL - -* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. - -* However, if revisions are enabled on the destination database, - whenever the ETL process sends a modified document and the target document is overwritten, - a new revision will be created for the document in the target database as expected. - - - -## Revisions and Backup - -Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. - - - -## Revisions and Data Subscriptions - -* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). - - - -## Revisions Import and Export - -* Revisions can be imported and exported with a `.ravendbdump` file - from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio - -* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). - - ![Import from Live Server](./assets/import-from-live-server.png) - - - - diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-java.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-java.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/_overview-python.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/content/_overview-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/configure-revisions.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/configure-revisions.mdx index bfdb4dc68d..3d01fbd6b9 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/configure-revisions.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/configure-revisions.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConfigureRevisionsCsharp from './_configure-revisions-csharp.mdx'; -import ConfigureRevisionsJava from './_configure-revisions-java.mdx'; -import ConfigureRevisionsPython from './_configure-revisions-python.mdx'; -import ConfigureRevisionsPhp from './_configure-revisions-php.mdx'; -import ConfigureRevisionsNodejs from './_configure-revisions-nodejs.mdx'; +import ConfigureRevisionsCsharp from './content/_configure-revisions-csharp.mdx'; +import ConfigureRevisionsJava from './content/_configure-revisions-java.mdx'; +import ConfigureRevisionsPython from './content/_configure-revisions-python.mdx'; +import ConfigureRevisionsPhp from './content/_configure-revisions-php.mdx'; +import ConfigureRevisionsNodejs from './content/_configure-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx index eb632e3ae5..2390b38588 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ConflictRevisionsConfigurationCsharp from './_conflict-revisions-configuration-csharp.mdx'; -import ConflictRevisionsConfigurationPhp from './_conflict-revisions-configuration-php.mdx'; -import ConflictRevisionsConfigurationNodejs from './_conflict-revisions-configuration-nodejs.mdx'; +import ConflictRevisionsConfigurationCsharp from './content/_conflict-revisions-configuration-csharp.mdx'; +import ConflictRevisionsConfigurationPhp from './content/_conflict-revisions-configuration-php.mdx'; +import ConflictRevisionsConfigurationNodejs from './content/_conflict-revisions-configuration-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-java.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_configure-revisions-python.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_configure-revisions-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_conflict-revisions-configuration-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_conflict-revisions-configuration-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_delete-revisions-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_delete-revisions-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/_get-revisions-python.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/content/_get-revisions-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/delete-revisions.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/delete-revisions.mdx index 52d57a6d9e..6ac42ce584 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/delete-revisions.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/delete-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteRevisionsCsharp from './_delete-revisions-csharp.mdx'; +import DeleteRevisionsCsharp from './content/_delete-revisions-csharp.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/get-revisions.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/get-revisions.mdx index 2e3658bb4b..4068f560dc 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/get-revisions.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/operations/get-revisions.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetRevisionsCsharp from './_get-revisions-csharp.mdx'; -import GetRevisionsPython from './_get-revisions-python.mdx'; -import GetRevisionsPhp from './_get-revisions-php.mdx'; -import GetRevisionsNodejs from './_get-revisions-nodejs.mdx'; +import GetRevisionsCsharp from './content/_get-revisions-csharp.mdx'; +import GetRevisionsPython from './content/_get-revisions-python.mdx'; +import GetRevisionsPhp from './content/_get-revisions-php.mdx'; +import GetRevisionsNodejs from './content/_get-revisions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/overview.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/overview.mdx index 215bc24729..601004d5eb 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/overview.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/overview.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewJava from './_overview-java.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewPhp from './_overview-php.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewJava from './content/_overview-java.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewPhp from './content/_overview-php.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_counting-python.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_counting-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_including-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_including-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-java.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-java.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-php.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/client-api/session/_loading-python.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/client-api/session/content/_loading-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/counting.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/counting.mdx index ea402f78a5..f9d32243a9 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/counting.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/counting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountingCsharp from './_counting-csharp.mdx'; -import CountingPython from './_counting-python.mdx'; -import CountingPhp from './_counting-php.mdx'; -import CountingNodejs from './_counting-nodejs.mdx'; +import CountingCsharp from './content/_counting-csharp.mdx'; +import CountingPython from './content/_counting-python.mdx'; +import CountingPhp from './content/_counting-php.mdx'; +import CountingNodejs from './content/_counting-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/including.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/including.mdx index cf10517448..cdeb95aaec 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/including.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/including.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludingCsharp from './_including-csharp.mdx'; -import IncludingPhp from './_including-php.mdx'; -import IncludingNodejs from './_including-nodejs.mdx'; +import IncludingCsharp from './content/_including-csharp.mdx'; +import IncludingPhp from './content/_including-php.mdx'; +import IncludingNodejs from './content/_including-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/loading.mdx b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/loading.mdx index 2e83030bab..4e6789ea62 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/loading.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/client-api/session/loading.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import LoadingCsharp from './_loading-csharp.mdx'; -import LoadingJava from './_loading-java.mdx'; -import LoadingPython from './_loading-python.mdx'; -import LoadingPhp from './_loading-php.mdx'; -import LoadingNodejs from './_loading-nodejs.mdx'; +import LoadingCsharp from './content/_loading-csharp.mdx'; +import LoadingJava from './content/_loading-java.mdx'; +import LoadingPython from './content/_loading-python.mdx'; +import LoadingPhp from './content/_loading-php.mdx'; +import LoadingNodejs from './content/_loading-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..3adf41e824 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-csharp.mdx @@ -0,0 +1,327 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions are moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +var company = new Company { + Name = "CompanyName" + }; + +session.Store(company); +companyId = company.Id; +session.SaveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +session.Advanced.Revisions.ForceRevisionCreationFor(company); + +// Call SaveChanges for the revision to be created +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +{`// Force revision creation by ID +// ============================= + +session.Advanced.Revisions.ForceRevisionCreationFor(companyId); +session.SaveChanges(); + +var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; +Assert.Equal(1, revisionsCount); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== + +// Force revision creation by entity. +// Can be used with tracked entities only. +void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + +// Force revision creation by document ID. +void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +`} + + + +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | + + + +{`public enum ForceRevisionStrategy +\{ + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before +\} +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..60af21c283 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-nodejs.mdx @@ -0,0 +1,324 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + + + + +{`// Force revision creation by entity +// ================================= + +const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Forcing the creation of a revision by entity can be performed +// only when the entity is tracked, after the document is stored. +await session.advanced.revisions.forceRevisionCreationFor(company); + +// Must call 'saveChanges' for the revision to be created +await session.saveChanges(); + +// Get existing revisions: +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +{`const company = new Company(); +company.name = "CompanyName"; + +const session = documentStore.openSession(); +await session.store(company); +await session.saveChanges(); + +// Force revision creation by ID +const companyId = company.id; +await session.advanced.revisions.forceRevisionCreationFor(companyId); +await session.saveChanges(); + +const revisions = await session.advanced.revisions.getFor(company.id); +const revisionsCount = revisions.length; + +assert.equal(revisionsCount, 1); +`} + + + + +**Syntax**: + + + +{`// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +`} + + + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-python.mdx new file mode 100644 index 0000000000..ad06ca3084 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_overview-python.mdx @@ -0,0 +1,287 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions.mdx) to any of its recorded revisions. + + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + +* Managed via the Client API or from the Studio, revisions can be created **automatically** or **manually**: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) below. +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview.mdx#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview.mdx#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview.mdx#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview.mdx#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview.mdx#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview.mdx#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview.mdx#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview.mdx#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview.mdx#force-revision-creation) + + +## Revisions configuration + +* The revisions configuration enables or disables the creation and purging of revisions for documents, + and optionally limits the number of revisions retained per document. + +* By default, the revisions feature is **disabled** for all collections: no revisions are created or purged for any document. + You can modify this behavior and other revisions settings by applying a revisions configuration to the database. + The revisions configuration is stored in the database record. + + + + #### Conflict Revisions + + Revisions created for **conflicting documents** are a special case that is not covered in this article. + + * Conflict revisions are **enabled** by default. + * Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration.mdx) + * Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions.mdx#editing-the-conflicting-document-defaults) + + +#### Defining a revisions configuration + +You can apply a revisions configuration using the Studio or the Client API: + +* Via Studio: + * Manage the revisions configuration in the [Document Revisions Settings](../../studio/database/settings/document-revisions.mdx) view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation to define and apply a revisions configuration. +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: + +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. + +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + +#### Revisions configuration options + +A revisions configuration defines - + +* Whether to enable or disable revisions creation: + * If the revisions configuration is **Enabled** for a collection, + creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, + and optionally the purging of existing revisions for the document. + * If the revisions configuration is **Disabled** for a collection, + RavenDB will **not** automatically create or purge revisions for documents in this collection. + +* Whether to limit the number of revisions that can be kept per document. + RavenDB will only purge revisions if they exceed the limits you set. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx). +#### Revisions configuration execution + +Creating a revisions configuration does **not** immediately trigger its execution. +Default and collection-specific configurations are executed when - + +1. **Documents are Created, Modified, or Deleted**. + When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. + If the revisions configuration is enabled for this collection: + * A revision of the document will be created. + * Existing revisions will optionally be purged according to the limits set in the configuration. + +2. **Enforce Configuration is applied**. + [Enforcing the configuration](../../studio/database/settings/document-revisions.mdx#enforce-configuration) applies the defined revisions configuration immediately throughout the database, **purging** all the revisions pending purging + according to default settings or collection-specific configurations, and **deleting** all revisions that no configuration applies to. + + * Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. + Be aware that this operation may require substantial server resources, so time it accordingly. + * Revisions that were created over time but to which no configuration currently applies will be deleted. + Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep. + +#### Enabling and disabling revisions for existing documents + +* When revisions creation is **Enabled** for a populated collection: + * The first revision will be created for an existing document the next time the document is modified + (recording the document **after** its modification), or when the document is deleted. + +* When revisions creation is **Disabled** for a collection after revisions have been created: + * The creation of new revisions and the purging of existing revisions will stop. + * Existing revisions will remain intact. + + + +## How it works + +Let's play with revisions a little to get a taste of its advantages. + +1. **Enable Revisions** so we can experiment with the feature. + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions.mdx) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions.mdx) _Store_ operation. + + ![Enable Revisions for the Users Collection](../assets/revisions-1.png) + +2. **Create a new document in the `Users` collection**. + We will follow the automatic creation of revisions for this document. + You can create the document in the [Studio](../../studio/database/documents/create-new-document.mdx#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities.mdx#example) method. + + ![Create a Document](../assets/revisions-2.png) + +3. **Inspect the new document's [Revisions Tab](../../studio/database/document-extensions/revisions/revisions-overview.mdx#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](../assets/revisions-3.png) + + Click the _"See the current document"_ button to return to the parent document view. + +4. **Modify and Save the document**. + This will create a second revision. + + ![Revision for Document Modification](../assets/revisions-4.png) + +5. **Delete the document**. + Though you deleted the document, its **audit trail** is **not lost**: all its revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + including a new revision (called "Delete Revision"), created to indicate that the document was deleted. + + + * A "Delete Revision" is created only if the deleted document has revisions. + * If a document has no revisions, a "Delete Revision" will be created only if the Revisions Configuration is set and enabled for its collection. + + + To see the revisions created for the document before it was deleted: + * Open the `Documents > Revisions Bin` section in the Studio + * Click the deleted document's ID + + ![Revisions Bin](../assets/revisions-5.png) + +6. **Restore the document**. + Even after a document is deleted, you can still restore it from one of its revisions. + To do so, open the revision containing the content you want to restore. + Click _Clone_ to create a new document from that revision. + + ![Revisions Bin](../assets/revisions-6.png) + + Save the new document using the exact **same ID** as the deleted document. + This will restore all revisions of the deleted document from the Revisions Bin and associate them with the new document. + + Opening the document’s Revisions Tab will show the full audit trail, + including the "Delete Revision" created when the original document was deleted and the new revision created when the restored document was saved. + + ![Restored Revisions](../assets/revisions-7.png) + + + +## Revisions storage + +##### Revisions storage + +When a document revision is created, a full version of the modified document is stored in the revisions storage, +using the same blittable JSON document format as regular documents. +##### Revisions Compression + +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression.mdx#set-compression-for-selected-collections). +* Individual fields are compressed as they are compressed in regular documents: + any text field exceeding 128 bytes is compressed. + Learn more about documents compression in [Documents Compression](../../server/storage/documents-compression.mdx). +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + +## Revisions storage + + + +##### Revisions documents storage +* The creation of a document revision stores a full version of the modified document in the revisions storage, + in the same **blittable JSON document** format as that of regular documents. + +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration.mdx#databasescompressioncompressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression.mdx) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. + + + + +##### Revisions document extensions storage +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) about revisions and **attachments**. + + + + +## Force revision creation + +So far we've discussed the automatic creation of revisions when the feature is enabled. +However, you can also **force the creation** of a document revision, whether the feature is enabled or not. + +This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, +e.g. take a snapshot of the document as a precaution before editing it. + +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview.mdx#force-revision-creation-via-the-client-api). +* A revision **will** be created even if the revisions configuration is disabled for the document's collection. +* A revision **will** be created even if the document has not been modified + (unless the document has revisions and the latest revision contains the current document contents). +* Similar to revisions created automatically due to the revisions configuration, + deleting a document with a manually created revision will move the revision to the [Revisions Bin](../../studio/database/document-extensions/revisions/revisions-bin.mdx), + and a "Delete Revision" will be created. +##### Force revision creation via the Studio + +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions Tab in the document view. + +![Create a revision manually](../assets/revisions-8.png) +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + + + +{`with self.store.open_session() as session: + company = session.load(company_id, Company) + company.name = "HR V2" + + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() + + revisions = session.advanced.revisions.get_for(company.Id, Company) + revisions_count = len(revisions) + + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx new file mode 100644 index 0000000000..335c0a220b --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-csharp.mdx @@ -0,0 +1,264 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. +### Extract counters data from revisions: + +Use [GetMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, +and then extract the counters' data. + + + + +{`// Use GetMetadataFor to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = session + .Advanced.Revisions.GetMetadataFor(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + +{`// Use GetMetadataForAsync to get revisions metadata for document 'orders/1-A' +List revisionsMetadata = await asyncSession + .Advanced.Revisions.GetMetadataForAsync(id: "orders/1-A"); + +// Extract the counters data from the metadata +List countersDataInRevisions = revisionsMetadata + .Where(metadata => + metadata.ContainsKey(Constants.Documents.Metadata.RevisionCounters)) + .Select(metadata => + (MetadataAsDictionary)metadata[Constants.Documents.Metadata.RevisionCounters]) + .ToList(); +`} + + + + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-java.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/revisions/_revisions-and-other-features-java.mdx rename to versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..8d5e984b45 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-nodejs.mdx @@ -0,0 +1,308 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + + + +**Revisions creation** + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing counter. + + + + + +**Stored data** + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + + + + + + +**Reverted data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, + the counters from the revision are restored to functionality along with their values. + + + + + +**Extract counters data from revisions** + +* Use [getMetadataFor](../../document-extensions/revisions/client-api/session/loading.mdx#get-revisions-metadata) to get the revisions metadata for a specified document, + and then extract the counters' data. + + + +{`// Use getMetadataFor to get revisions metadata for document 'orders/1-A' +const revisionsMetadata = await session.advanced.revisions.getMetadataFor("orders/1-A"); + +// Extract the counters data from the metadata +const countersDataInRevisions = revisionsMetadata + .filter(x => !!x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]) + .map(x => x[CONSTANTS.Documents.Metadata.REVISION_COUNTERS]); +`} + + + + + + + +## Revisions and Time Series + + + +**Revisions Creation** + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). + + + + + +**Stored Data** + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + + + +## Revisions and Attachments + + + +**Revisions Creation** + +* A document revision will be created when: + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. + + + + + +**Stored Data** + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + + + + + + +**Reverted Data** + +* When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, + the attachments are restored to their state when the revision was created. + + + + + +## Revisions and Replication + + + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + + + +## Revisions and ETL + + + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + + + +## Revisions and Backup + + + +* Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + + + +## Revisions and Data Subscriptions + + + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + + + +## Revisions Import and Export + + + +* Revisions can be imported and exported with a `.ravendbdump` file: + * Using [the Client API](../../client-api/smuggler/what-is-smuggler.mdx) + * From the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-php.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-php.mdx new file mode 100644 index 0000000000..6bf087d689 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-php.mdx @@ -0,0 +1,217 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-python.mdx b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-python.mdx new file mode 100644 index 0000000000..ab3a281b0b --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/content/_revisions-and-other-features-python.mdx @@ -0,0 +1,224 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes relationships between Revisions and other RavenDB features, including - + * When is revisions creation triggered by other features + * How revisions are supported by other features + +* In this page: + * [Revisions and Counters](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-counters) + * [Revisions and Time Series](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-time-series) + * [Revisions and Attachments](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-attachments) + * [Revisions and Replication](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-replication) + * [Revisions and ETL](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-etl) + * [Revisions and Backup](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-backup) + * [Revisions and Data Subscriptions](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-and-data-subscriptions) + * [Revisions Import and Export](../../document-extensions/revisions/revisions-and-other-features.mdx#revisions-import-and-export) + + +## Revisions and Counters + +### Revisions creation: + +* A document revision will be created when: + * A new counter is **created** on the document. + * A counter is **deleted** from the document. + +* A revision will Not be created upon modifying the value of an existing [counter](../../document-extensions/counters/overview.mdx). +### Stored data: + +* A revision that is created for a document that contains counters + will have the `@counters-snapshot` property in its **metadata**. + +* This property holds the counters' names and values at the time when the revision was created. + +* The counter's value stored in the revision's metadata is the **accumulated value** from all nodes. + It does not specify the value of the counter on each individual node. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@counters-snapshot": \{ + "counterName1": 7, + "counterName2": 42 + \}, + ... + \} +\} +`} + + +### Reverted data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has counters, +the counters from the revision are restored to functionality along with their values. + + + +## Revisions and Time Series + +### Revisions Creation: + +* A document revision will be created when: + * A new time series is **created** on the document. + * A time series is **deleted** from the document. + (A time series is deleted from a document when all its entries are deleted) + +* A revision will Not be created upon modifying the values of an existing [time series](../../document-extensions/timeseries/overview.mdx). +### Stored Data: + +* A revision that is created for a document that contains time series + will have the `@timeseries-snapshot` property in its **metadata**. + +* This property does Not hold the time series values data, + it only contains the following information for the time when the revision was created: + * The time series names + * The number of entries in each time series + * Dates of the first and last entry in each time series + +* Read more about Revisions and Time Series [here](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions). + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@timeseries-snapshot": \{ + "timeSeriesName1": \{ + "Count": 5, + "Start": "2023-03-22T11:25:00.9110000Z", + "End": "2023-03-22T11:28:34.9110000Z" + \}, + "timeSeriesName2": \{ + "Count": 10, + "Start": "2023-03-22T11:26:00.3950000Z", + "End": "2023-03-22T11:28:48.3950000Z" + \} + \}, + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has a time series: + +* If the current document **contains** a time series name as in the revision: + * The reverted document will keep the time series entries & values as it was in the current document. + * Time series entries and values from the revision are Not restored. + +* If the current document **doesn't contain** a time series name as in the revision, + or if the document itself was deleted: + * The reverted document will have the time series from the revision + * However, the entries count will be 0 + + + +## Revisions and Attachments + +### Revisions Creation: + +A document revision will be created when: + + * A new [attachment](../../document-extensions/attachments/what-are-attachments.mdx) is **added** to the document. + * An attachment is **deleted** from the document. +### Stored Data: + +* A revision that is created for a document with attachments + will have the `@attachments` property in its **metadata**. + +* This property does Not hold the actual attachments, as the files are stored in **separate storage**. + The property only contains the following information for each attachment the document had when the revision was created: + * Attachment file name + * File content type + * File size + * A hash string (a reference to the file in the storage) + +* Existing attachment files in the storage are Not duplicated per revision that is created when the document itself is modified. + +* An attachment file is removed from RavenDB's storage only when there is no live document or a revision that refers to it. + +* Sample revision metadata: + + +{`\{ + ... + "@metadata": \{ + "@attachments": [ + \{ + "Name": "attachmentFileName.png", + "ContentType": "image/png", + "Size": 33241, + "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=", + \}, + ], + ... + \} +\} +`} + + +### Reverted Data: + +When a document is [reverted](../../document-extensions/revisions/revert-revisions.mdx) to a revision that has attachments, +the attachments are restored to their state when the revision was created. + + + +## Revisions and Replication + +* Revisions are transferred during [replication](../../server/clustering/replication/replication-overview.mdx) from one database instance to another. + +* The revisions will be replicated by all replication types: + * [Internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication) + * [External replication](../../server/clustering/replication/replication-overview.mdx#external-replication) + * [Hub/Sink replication](../../server/clustering/replication/replication-overview.mdx#hubsink-replication) + +* Revisions can [help keep data consistency](../../server/clustering/replication/replication-overview.mdx#how-revisions-replication-help-data-consistency). + + + +## Revisions and ETL + +* An [ETL](../../server/ongoing-tasks/etl/raven.mdx) ongoing task does Not send revisions to the destination database. + +* However, if revisions are enabled on the destination database, + whenever the ETL process sends a modified document and the target document is overwritten, + a new revision will be created for the document in the target database as expected. + + + +## Revisions and Backup + +Revisions are [backed up](../../server/ongoing-tasks/backup-overview.mdx#backup-contents) both by a logical-backup and by a snapshot. + + + +## Revisions and Data Subscriptions + +* Learn about revisions and data subscriptions [here](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.mdx). + + + +## Revisions Import and Export + +* Revisions can be imported and exported with a `.ravendbdump` file + from the [import](../../studio/database/tasks/import-data/import-data-file.mdx#import-options) and [export](../../studio/database/tasks/export-database.mdx#export-options) views in the Studio + +* Revisions can be imported when migrating data from another [live RavenDB server](../../studio/database/tasks/import-data/import-from-ravendb.mdx#step-#4:-set-import-options). + + ![Import from Live Server](../assets/import-from-live-server.png) + + + + diff --git a/versioned_docs/version-7.1/document-extensions/revisions/overview.mdx b/versioned_docs/version-7.1/document-extensions/revisions/overview.mdx index 6345e084bd..0485de548f 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/overview.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/overview.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "python", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewPython from './_overview-python.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewPython from './content/_overview-python.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx deleted file mode 100644 index 1ca0053750..0000000000 --- a/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/_revert-documents-to-specific-revisions-csharp.mdx +++ /dev/null @@ -1,221 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ContentFrame from '@site/src/components/ContentFrame'; -import Panel from '@site/src/components/Panel'; - - - -* This article describes how to revert specific documents to **specific revisions**. - To revert documents from all collections (or from selected collections) to a **specific point in time**, - see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). - -* In this article: - * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) - * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) - * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) - * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) - * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) - - - - - -* When reverting to a specific revision, - the document content will be overwritten by the content of the specified revision. - -* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: - * **When revisions are ENABLED**: - Reverting the document creates a new revision containing the content of the target revision. - * **When revisions are DISABLED**: - The document is reverted to the target revision without creating a new revision. - -* In addition to the document itself, reverting will impact _Document Extensions_ as follows: - * **Attachments**: - If the target revision owns attachments, they are restored to their state when the revision was created. - * **Counters**: - If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. - * **Time series**: - Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). - - - - - -* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. - -* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). - To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). - -* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. - The document content will be overwritten by the content of the specified revision. - -* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. - -* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, - the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. - ---- - -### How to obtain a revision's change-vector: - -The change-vector of a revision can be obtained via: - - * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) - * Or from the document view in the Studio - -![Get revision CV](./assets/get-cv-for-revision.png) - -1. Go to the Revisions tab in the document view. -2. Click a revision to view -3. The document view will display the content of the revision. - This top label indicates that you are viewing a revision and not the current document. -4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. - - - - - -Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. -In this example, we revert document _orders/1-A_ to its very first revision. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the document you wish to revert - // ============================================================== - - var revisionsMetadata = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "Orders/1-A"); - - // Get the change-vector of the revision you wish to revert to: - // ============================================================ - - // Note: revisionsMetadata[0] is the latest revision, - // so specify the index of the revision you want. - // In this example, it will be the very first revision of the document: - - var numberOfRevisions = revisionsMetadata.Count(); - var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document ID and the change-vector of the revision to revert to - new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); -} -``` - - - - - - - -You can use the operation to revert multiple documents. -Note: The documents do not need to belong to the same collection. - - - -```csharp -using (var session = store.OpenSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = session.Advanced.Revisions - .GetMetadataFor(id: "orders/1-A"); - var revisionsMetadata2 = session.Advanced.Revisions - .GetMetadataFor(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - store.Operations.Send( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - -```csharp -using (var asyncSession = store.OpenAsyncSession()) -{ - // Get the revisions metadata for the documents you wish to revert - var revisionsMetadata1 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "orders/1-A"); - var revisionsMetadata2 = await asyncSession.Advanced.Revisions - .GetMetadataForAsync(id: "users/999"); - - // Get the change-vector of the revisions you wish to revert to - var changeVector1 = revisionsMetadata1[2] - .GetString(Constants.Documents.Metadata.ChangeVector); - var changeVector2 = revisionsMetadata1[3] - .GetString(Constants.Documents.Metadata.ChangeVector); - - // Execute the operation - await store.Operations.SendAsync( - // Pass the document IDs and the change-vector of the revisions to revert to - new RevertRevisionsByIdOperation(new Dictionary() - { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); -} -``` - - - - - - - -### `RevertRevisionsByIdOperation` - - -```csharp -Available overloads: -==================== -public RevertRevisionsByIdOperation(string id, string cv); -public RevertRevisionsByIdOperation(Dictionary idToChangeVector); -``` - - -| Parameter | Type | Description | -|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| **id** | `string` | The ID of the document to revert. | -| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | -| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | - - \ No newline at end of file diff --git a/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx b/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx new file mode 100644 index 0000000000..df41e24beb --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/content/_revert-documents-to-specific-revisions-csharp.mdx @@ -0,0 +1,221 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* This article describes how to revert specific documents to **specific revisions**. + To revert documents from all collections (or from selected collections) to a **specific point in time**, + see [Revert documents to specific time](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-time.mdx). + +* In this article: + * [Overview](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#overview) + * [Revert documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-documents) + * [Revert single document](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-single-document) + * [Revert multiple documents](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#revert-multiple-documents) + * [Syntax](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx#syntax) + + + + + +* When reverting to a specific revision, + the document content will be overwritten by the content of the specified revision. + +* Reverting a document to a specific revision can be executed even if the revisions configuration is disabled: + * **When revisions are ENABLED**: + Reverting the document creates a new revision containing the content of the target revision. + * **When revisions are DISABLED**: + The document is reverted to the target revision without creating a new revision. + +* In addition to the document itself, reverting will impact _Document Extensions_ as follows: + * **Attachments**: + If the target revision owns attachments, they are restored to their state when the revision was created. + * **Counters**: + If the target revision owns counters, they are restored to functionality with their values at the time the revision was created. + * **Time series**: + Time series data is Not reverted. Learn more in [Revisions and time series](../../../document-extensions/revisions/revisions-and-other-features.mdx#reverted-data-1). + + + + + +* You can revert single or multiple documents to specific revisions using the `RevertRevisionsByIdOperation` operation. + +* By default, the operation will be applied to the [default database](../../../client-api/setting-up-default-database.mdx). + To operate on a different database, see [switch operations to different database](../../../client-api/operations/how-to/switch-operations-to-a-different-database.mdx). + +* To revert a document to a specific revision, provide the document ID and the change-vector of the target revision to the `RevertRevisionsByIdOperation` operation. + The document content will be overwritten by the content of the specified revision. + +* An exception will be thrown if the revision's change-vector is not found, does not exist for the specified document, or belongs to a different document. + +* When executing this operation on a document that had revisions and was deleted, placing it in the Revisions Bin, + the document will be **recreated** with the content of the specified target revision and will be removed from the Revisions Bin. + +--- + +### How to obtain a revision's change-vector: + +The change-vector of a revision can be obtained via: + + * The Client API - follow the code in the examples [below](../../../document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions#revert-single-document) + * Or from the document view in the Studio + +![Get revision CV](../assets/get-cv-for-revision.png) + +1. Go to the Revisions tab in the document view. +2. Click a revision to view +3. The document view will display the content of the revision. + This top label indicates that you are viewing a revision and not the current document. +4. Click the copy button in the Properties pane to copy this revision's change-vector to your clipboard. + + + + + +Using RavenDB's sample data, document _orders/1-A_ has a total of 7 revisions. +In this example, we revert document _orders/1-A_ to its very first revision. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("orders/1-A", revisionChangeVector)); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the document you wish to revert + // ============================================================== + + var revisionsMetadata = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "Orders/1-A"); + + // Get the change-vector of the revision you wish to revert to: + // ============================================================ + + // Note: revisionsMetadata[0] is the latest revision, + // so specify the index of the revision you want. + // In this example, it will be the very first revision of the document: + + var numberOfRevisions = revisionsMetadata.Count(); + var revisionChangeVector = revisionsMetadata[numberOfRevisions-1] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document ID and the change-vector of the revision to revert to + new RevertRevisionsByIdOperation("Orders/1-A", revisionChangeVector)); +} +``` + + + + + + + +You can use the operation to revert multiple documents. +Note: The documents do not need to belong to the same collection. + + + +```csharp +using (var session = store.OpenSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = session.Advanced.Revisions + .GetMetadataFor(id: "orders/1-A"); + var revisionsMetadata2 = session.Advanced.Revisions + .GetMetadataFor(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + store.Operations.Send( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + +```csharp +using (var asyncSession = store.OpenAsyncSession()) +{ + // Get the revisions metadata for the documents you wish to revert + var revisionsMetadata1 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "orders/1-A"); + var revisionsMetadata2 = await asyncSession.Advanced.Revisions + .GetMetadataForAsync(id: "users/999"); + + // Get the change-vector of the revisions you wish to revert to + var changeVector1 = revisionsMetadata1[2] + .GetString(Constants.Documents.Metadata.ChangeVector); + var changeVector2 = revisionsMetadata1[3] + .GetString(Constants.Documents.Metadata.ChangeVector); + + // Execute the operation + await store.Operations.SendAsync( + // Pass the document IDs and the change-vector of the revisions to revert to + new RevertRevisionsByIdOperation(new Dictionary() + { { "orders/1-A", changeVector1 }, { "users/999", changeVector2 } })); +} +``` + + + + + + + +### `RevertRevisionsByIdOperation` + + +```csharp +Available overloads: +==================== +public RevertRevisionsByIdOperation(string id, string cv); +public RevertRevisionsByIdOperation(Dictionary idToChangeVector); +``` + + +| Parameter | Type | Description | +|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| **id** | `string` | The ID of the document to revert. | +| **cv** | `string` | The change-vector of the revision to which the document should be reverted. | +| **idToChangeVector** | `Dictionary` | A dictionary where each key is a document ID, and each value is the change-vector of the revision to which the document should be reverted. | + + \ No newline at end of file diff --git a/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx b/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx index 7f83c35e84..4bff881ca7 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/revert-documents-to-revisions/revert-documents-to-specific-revisions.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevertDocumentsToSpecificRevisionsCsharp from './_revert-documents-to-specific-revisions-csharp.mdx'; +import RevertDocumentsToSpecificRevisionsCsharp from './content/_revert-documents-to-specific-revisions-csharp.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/revisions/revisions-and-other-features.mdx b/versioned_docs/version-7.1/document-extensions/revisions/revisions-and-other-features.mdx index dd80b671dc..38db72b2c8 100644 --- a/versioned_docs/version-7.1/document-extensions/revisions/revisions-and-other-features.mdx +++ b/versioned_docs/version-7.1/document-extensions/revisions/revisions-and-other-features.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RevisionsAndOtherFeaturesJava from './_revisions-and-other-features-java.mdx'; -import RevisionsAndOtherFeaturesCsharp from './_revisions-and-other-features-csharp.mdx'; -import RevisionsAndOtherFeaturesPython from './_revisions-and-other-features-python.mdx'; -import RevisionsAndOtherFeaturesPhp from './_revisions-and-other-features-php.mdx'; -import RevisionsAndOtherFeaturesNodejs from './_revisions-and-other-features-nodejs.mdx'; +import RevisionsAndOtherFeaturesJava from './content/_revisions-and-other-features-java.mdx'; +import RevisionsAndOtherFeaturesCsharp from './content/_revisions-and-other-features-csharp.mdx'; +import RevisionsAndOtherFeaturesPython from './content/_revisions-and-other-features-python.mdx'; +import RevisionsAndOtherFeaturesPhp from './content/_revisions-and-other-features-php.mdx'; +import RevisionsAndOtherFeaturesNodejs from './content/_revisions-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-csharp.mdx deleted file mode 100644 index 5972ad8ca5..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-csharp.mdx +++ /dev/null @@ -1,300 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`var oneWeek = TimeValue.FromDays(7); -var fiveYears = TimeValue.FromYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -var rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - oneWeek, // Aggregation time, roll-up the data for each week - fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -var timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration -\{ - Policies = new List \{ rollupPolicy \}, - RawPolicy = rawPolicy -\}; - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -var rawData = session - .TimeSeriesFor("companies/91-A", "StockPrices") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -var rollupData = session - .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .Get(DateTime.MinValue, DateTime.MaxValue); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = session - .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) - .Get(DateTime.MinValue, DateTime.MaxValue); - -// The raw time series has 100 entries -Assert.Equal(rawData.Length, 100); -Assert.Equal(rawData[0].IsRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -Assert.Equal(rollupData.Length, 22); -Assert.Equal(rollupData[0].IsRollup, true); -`} - - - - - -## Syntax - -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`public class RawTimeSeriesPolicy : TimeSeriesPolicy -\{ - public TimeValue RetentionTime; -\} - -public class TimeSeriesPolicy -\{ - public string Name; - public TimeValue RetentionTime; \{ get; protected set; \} - public TimeValue AggregationTime; \{ get; private set; \} -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | -| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`public struct TimeValue -\{ - public static TimeValue FromSeconds(int seconds); - public static TimeValue FromMinutes(int minutes); - public static TimeValue FromHours(int hours); - public static TimeValue FromDays(int days); - public static TimeValue FromMonths(int months); - public static TimeValue FromYears(int years); -\} -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`public class TimeSeriesConfiguration -\{ - public Dictionary Collections; -\} - -public class TimeSeriesCollectionConfiguration -\{ - public bool Disabled; - public List Policies; - public RawTimeSeriesPolicy RawPolicy; -\} -`} - - - -| Property | Description | -|-----------------|---------------------------------------------------------------------------------------------------------------------------| -| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **Policies** | Populate this `List` with your rollup policies. | -| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Casting time series entries - -Time series entries are of one of the following classes: - - - -{`public class TimeSeriesEntry \{ \} -public class TimeSeriesEntry : TimeSeriesEntry \{ \} -public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} -`} - - - -If you have an existing rollup entry of type `TimeSeriesEntry`, -you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. - - - -{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); -`} - - - -You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. -Its values will consist of all the `First` values of the rollup entry. - - - -{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); -TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; -`} - - - -Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx deleted file mode 100644 index 2c0c4c1a5b..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-nodejs.mdx +++ /dev/null @@ -1,257 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* *First* - the value of the first entry in the frame. -* *Last* - the value of the last entry. -* *Min* - the smallest value. -* *Max* - the largest value. -* *Sum* - the sum of all the values in the frame. -* *Count* - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`// Define a policy on the RAW time series data: -// ============================================ -const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years - -// Define a ROLLUP policy: -// ======================= -const rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week - TimeValue.ofYears(5)); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -const collectionConfig = new TimeSeriesCollectionConfiguration(); -collectionConfig.rawPolicy = rawPolicy; -collectionConfig.policies = [rollupPolicy]; - -const timeSeriesConfig = new TimeSeriesConfiguration(); -timeSeriesConfig.collections.set("Companies", collectionConfig); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -const rawData = await session - .timeSeriesFor("companies/91-A", "StockPrices") - .get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -let rollupData = await session - .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - .get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -rollupData = await session - .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) - .get(); - -// The raw time series has 100 entries -assert.equal(rawData.length, 100); -assert.equal(rawData[0].isRollup, false); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -assert.equal(rollupData.length, 22); -assert.equal(rollupData[0].isRollup, true); -`} - - - - - -## Syntax -### The time series policies - -* Raw policy: - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ - retentionTime; // TimeValue -\} - -class TimeSeriesPolicy \{ - name; // string; - retentionTime // TimeValue - aggregationTime // TimeValue -\} -`} - - - -| Property | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | -| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue \{ - static ofSeconds(seconds); - static ofMinutes(minutes); - static ofHours(hours); - static ofDays(days); - static ofMonths(months); - static ofYears(years); -\} -`} - - - - -The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' -because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). -`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. - -### The time series configuration object - - - -{`class TimeSeriesConfiguration \{ - collections; // Map -\} - -class TimeSeriesCollectionConfiguration \{ - disabled; // boolean - policies; // TimeSeriesPolicy[] - rawPolicy; // RawTimeSeriesPolicy -\} -`} - - - -| Property | Description | -|-----------------|-------------------------------------------------------------------------------------------------------------------------| -| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** | Populate this list with your rollup policies. | -| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`ConfigureTimeSeriesOperation(configuration); -`} - - - -| Parameter | Description | -|-------------------|--------------------------------------------------------------| -| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-php.mdx deleted file mode 100644 index af9e9480f6..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-php.mdx +++ /dev/null @@ -1,334 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`$oneWeek = TimeValue::ofDays(7); -$fiveYears = TimeValue::ofYears(5); - -// Define a policy on the RAW time series data: -// ============================================ -$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years - -// Define a ROLLUP policy: -// ======================= -$rollupPolicy = new TimeSeriesPolicy( - "By1WeekFor1Year", // Name of policy - $oneWeek, // Aggregation time, roll-up the data for each week - $fiveYears); // Retention time, keep data for five years - -// Define the time series configuration for collection "Companies" (use above policies): -// ===================================================================================== -$companyConfig = new TimeSeriesCollectionConfiguration(); -$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); -$companyConfig->setRawPolicy($rawPolicy); - -$timeSeriesConfig = new TimeSeriesConfiguration(); -$timeSeriesConfig->setCollections([ - "Companies" => $companyConfig -]); - -// Deploy the time series configuration to the server -// by sending the 'ConfigureTimeSeriesOperation' operation: -// ======================================================== -$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); - -// NOTE: -// The time series entries in the RavenDB sample data are dated up to the year 2020. -// To ensure that you see the rollup time series created when running this example, -// the retention time should be set to exceed that year. -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`// Get all data from the RAW time series: -// ====================================== - -$rawData = $session - ->timeSeriesFor("companies/91-A", "StockPrices") - ->get(); - -// Get all data from the ROLLUP time series: -// ========================================= - -// Either - pass the rollup name explicitly to 'TimeSeriesFor': -$rollupData = $session - ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") - ->get(); - -// Or - get the rollup name by calling 'GetTimeSeriesName': -$rollupData = $session - ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) - ->get(); - -// The raw time series has 100 entries -$this->assertCount(100, $rawData); -$this->assertFalse($rawData[0]->isRollup()); - -// The rollup time series has only 22 entries -// as each entry aggregates 1 week's data from the raw time series -$this->assertCount(22, $rollupData); -$this->assertTrue($rollupData[0]->isRollup()); -`} - - - - - -## Syntax - -### The time series policies - -* `rawPolicy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-python.mdx deleted file mode 100644 index aa992fed57..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_rollup-and-retention-python.mdx +++ /dev/null @@ -1,309 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -Many time series applications produce massive amounts of data at a steady rate. -**Time Series Policies** help you manage your data in two ways: - -* Creating **Rollups**: - Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. - -* Limiting **Retention**: - Controlling the duration for which time series data is kept before deletion. - -* In this page: - * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) - * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) - * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) - * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) - * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) - - -## Time series policies - -#### What are rollups? - -A rollup is a time series that summarizes the data from another time series, -with each rollup entry representing a specific time frame in the original time series. -Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: - -* `First` - the value of the first entry in the frame. -* `Last` - the value of the last entry. -* `Min` - the smallest value. -* `Max` - the largest value. -* `Sum` - the sum of all the values in the frame. -* `Count` - the total number of entries in the frame. - -This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). - -#### Rollup policies: - -Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. - -* A rollup policy applies to all time series of every document in the given collection. - -* Each collection can be configured to have multiple policies which are applied sequentially: - * The raw time series is first rolled up using the policy with the shortest aggregation frame. - * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, - and so on. - -[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) -will transparently traverse over the rollups to retrieve the relevant results. - -Let's look at an example of rollup data: - -!["Rollup time series entries"](./assets/rollup-1.png) - -**1) Name:** -The name of a rollup time series has this format: `@` -It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. -In the image above these are "HeartRates" and "byHour" respectively. -For this reason, neither a time series name nor a policy name can have the character `@` in it. - -**2) Timestamp:** -The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. -So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* -(since milliseconds are the minimal resolution in RavenDB time series). -The timestamp for a rollup entry is the beginning of the frame it represents. - -For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: -`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. - -**3) Values:** -Each group of six values represents one value from the original entries. -If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: -the first six summarize the first raw value, the next six summarize the next raw value, and so on. -The aggregated values have the names: `"First ()", "Last ()", ...` respectively. - -Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. - - - -## Examples - -#### Create time series policies: - - - -{`# Policy for the original ("raw") time-series, -# to keep the data for one week -one_week = TimeValue.of_days(7) -raw_retention = RawTimeSeriesPolicy(one_week) - -# Roll-up the data for each day, -# and keep the results for one year -one_day = TimeValue.of_days(1) -one_year = TimeValue.of_years(1) -daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) - -# Enter the above policies into a -# time-series collection configuration -# for the collection 'Sales' -sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) - -# Enter the configuration for the Sales collection -# into a time-series configuration for the whole database -database_ts_config = TimeSeriesConfiguration() -database_ts_config.collections["Sales"] = sales_ts_config - -# Send the time-series configuration to the server -store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) -`} - - -#### Retrieve rollup data: - -* Retrieving entries from a rollup time series is similar to getting the raw time series data. - -* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). - - - -{`# Create local instance of the time-series "rawSales" -# in the document "sales/1" -raw_ts = session.time_series_for("sales/1", "rawSales") - -# Create local instance of the rollup time-series - first method: -daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") - -# Create local instance of the rollup time-series - second method: -# using the rollup policy itself and the raw time-series' name -rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) - -# Retrieve all the data from both time-series -raw_data = raw_ts.get(datetime.min, datetime.max) -rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) -`} - - - - - -## Syntax - -### The time series policies - -* `raw_policy` - * Used to define the retention time of the raw time series. - * Only one such policy per collection can be defined. - * Does not perform aggregation. - -* Rollup policy: - * Used to define the aggregation time frame and retention time for the rollup time series. - * Multiple policies can be defined per collection. - - - -{`class RawTimeSeriesPolicy(TimeSeriesPolicy): - def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): - ... - -class TimeSeriesPolicy: - def __init__( - self, - name: Optional[str] = None, - aggregation_time: Optional[TimeValue] = None, - retention_time: TimeValue = TimeValue.MAX_VALUE(), - ): - ... -`} - - - -| Property | Type | Description | -|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | -| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | -| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | - - - -{`class TimeValue: - def __init__(self, value: int, unit: TimeValueUnit): - self.value = value - self.unit = unit - - @classmethod - def of_seconds(cls, seconds: int) -> TimeValue: - return cls(seconds, TimeValueUnit.SECOND) - - @classmethod - def of_minutes(cls, minutes: int) -> TimeValue: - return cls(minutes * 60, TimeValueUnit.SECOND) - - @classmethod - def of_hours(cls, hours: int) -> TimeValue: - return cls(hours * 3600, TimeValueUnit.SECOND) - - @classmethod - def of_days(cls, days: int) -> TimeValue: - return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) - - @classmethod - def of_months(cls, months: int) -> TimeValue: - return cls(months, TimeValueUnit.MONTH) - - @classmethod - def of_years(cls, years: int) -> TimeValue: - return cls(12 * years, TimeValueUnit.MONTH) -`} - - - -Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. -These methods are used to define the aggregation and retention spans om time series policies. -### The time series configuration object - - - -{`class TimeSeriesConfiguration: - def __init__(self): - self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} - self.policy_check_frequency: Optional[datetime.timedelta] = None - self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None - -class TimeSeriesCollectionConfiguration: - def __init__( - self, - disabled: Optional[bool] = False, - policies: Optional[List[TimeSeriesPolicy]] = None, - raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), - ): - self.disabled = disabled - self.policies = policies - self.raw_policy = raw_policy -`} - - - -| Property | Type | Description | -|-----------------|------|-------------| -| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | -| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | -| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | -| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | -### The time series configuration operation - - - -{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) -`} - - - -Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). -### Time series entries - -Time series entries are of one of the following classes: - - - -{`class TimeSeriesEntry: - def __init__( - self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.rollup = rollup - -class TypedTimeSeriesEntry(Generic[_T_TSBindable]): - def __init__( - self, - timestamp: datetime.datetime = None, - tag: str = None, - values: List[int] = None, - is_rollup: bool = None, - value: _T_TSBindable = None, - ): - self.timestamp = timestamp - self.tag = tag - self.values = values - self.is_rollup = is_rollup - self.value = value - - -class TypedTimeSeriesRollupEntry(Generic[_T_Values]): - def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): - self._object_type = object_type - self.tag: Optional[str] = None - self.rollup = True - self.timestamp = timestamp - - self._first: Optional[_T_Values] = None - self._last: Optional[_T_Values] = None - self._max: Optional[_T_Values] = None - self._min: Optional[_T_Values] = None - self._sum: Optional[_T_Values] = None - self._count: Optional[_T_Values] = None - self._average: Optional[_T_Values] = None -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx deleted file mode 100644 index 9e9c202531..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-csharp.mdx +++ /dev/null @@ -1,115 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: - - - -{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx deleted file mode 100644 index bb63670643..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/_time-series-and-other-features-nodejs.mdx +++ /dev/null @@ -1,116 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* This page describes how time series interact with various other RavenDB features. - -* Features not listed here either have no special behavior regarding time series, - or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). - -* In this page: - * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) - * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) - * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) - * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) - - -## General features - -* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. -* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. -* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). -* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). -* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). - - - -## Smuggler - -[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file -or import database items from an existing file into the database. - -To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, -add the string `TimeSeries` to the `operateOnTypes` array: - - - -{`const options = new DatabaseSmugglerExportOptions(); -options.operateOnTypes = ["Documents", "TimeSeries"]; -`} - - - - - -## Ongoing tasks - -[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. -Some of these apply to time series data, while others do not. - -#### Tasks that apply to time series - -* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. -* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, - including documents' time series, using Hub and Sink tasks. -* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. - All kinds of backups include time series data: logical-backup and snapshot, full and incremental. -* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, - and _loads_ it to another RavenDB database on another server. - -#### Tasks that cannot be applied to time series - -* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. -* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. - - - -Support for time series in ETL is planned for one of the next releases. - - - - - -## Revisions - -[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. -They can be created manually or by setting a policy that creates them automatically on selected collections. - -Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. -This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. - -However, revisions are triggered / created manually if a _new_ time series is added to the document, -or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). - -#### The `@timeseries-snapshot` metadata property - -While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. -These details appear in the `@timeseries-snapshot` property within the document's metadata. -When a revision is viewed in the studio, this metadata property looks like this: - -![NoSQL Database Time Series Feature](./assets/TSSnapshot.png) - -This time series snapshot property can also be accessed by loading a revision in the client. -This is the general JSON format of the time series snapshot: - - - -{`"@metadata": \{ - ... - "@timeseries-snapshot": \{ - "": \{ - "Count": , - "Start": "", - "End": "" - \}, - "": \{ ... \} - \} -`} - - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx deleted file mode 100644 index 3ef3e53a10..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-csharp.mdx +++ /dev/null @@ -1,268 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the time series types on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in model classes that can be used as time series types. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series type - -To define a class for use as a time series type, mark the class properties (which represent the values) -with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. - -E.g.: - - - -{`public class RoutePoint -\{ - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "Latitude" and "Longitude" respectively. - [TimeSeriesValue(0)] public double Latitude; - [TimeSeriesValue(1)] public double Longitude; -\} -`} - - - -The class can then be used by time series methods like _Append_: - - - -{`// Append coordinates -session.TimeSeriesFor("users/john") - .Append(baseTime.AddHours(1), new RoutePoint - \{ - Latitude = 40.712776, - Longitude = -74.005974 - \}, "devices/Navigator"); -`} - - - - -A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: - - - -{`public void Deconstruct(out DateTime timestamp, out T value); -public void Deconstruct(out DateTime timestamp, out T value, out string tag); -`} - - - -#### Examples - -* In this example, we define a StockPrice type and use it when appending StockPrice entries. - - -{`public class StockPrice -\{ - [TimeSeriesValue(0)] public double Open; - [TimeSeriesValue(1)] public double Close; - [TimeSeriesValue(2)] public double High; - [TimeSeriesValue(3)] public double Low; - [TimeSeriesValue(4)] public double Volume; -\} -`} - - - - -{`using (var session = store.OpenSession()) -\{ - session.Store(new User \{ Name = "John" \}, "users/john"); - - // Call 'Append' with the custom StockPrice class - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(1), new StockPrice - \{ - Open = 52, - Close = 54, - High = 63.5, - Low = 51.4, - Volume = 9824, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(2), new StockPrice - \{ - Open = 54, - Close = 55, - High = 61.5, - Low = 49.4, - Volume = 8400, - \}, "companies/kitchenAppliances"); - - session.TimeSeriesFor("users/john") - .Append(baseTime.AddDays(3), new StockPrice - \{ - Open = 55, - Close = 57, - High = 65.5, - Low = 50, - Volume = 9020, - \}, "companies/kitchenAppliances"); - - session.SaveChanges(); -\} -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`goingUp = false; - -using (var session = store.OpenSession()) -\{ - // Call 'Get' with the custom StockPrice class type - TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") - .Get(); - - var closePriceDay1 = val[0].Value.Close; - var closePriceDay2 = val[1].Value.Close; - var closePriceDay3 = val[2].Value.Close; - - if ((closePriceDay2 > closePriceDay1) - && - (closePriceDay3 > closePriceDay2)) - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`using (var session = store.OpenSession()) -{ - var query = - session.Query() - .Where(c => c.Address.City == "New York") - // Use the StockPrice type in the time series query - .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) - .Where(ts => ts.Tag == "companies/kitchenAppliances") - .ToList()); - - List> queryResults = query.ToList(); - - var tsEntries = queryResults[0].Results; - - double volumeDay1 = tsEntries[0].Value.Volume; - double volumeDay2 = tsEntries[1].Value.Volume; - double volumeDay3 = tsEntries[2].Value.Volume; -} -`} - - - - -{`from "companies" as c -where Address.City = $p0 -select timeseries( - from c.StockPrices - between $p1 and $p2 - where (Tag == $p3)) -{ - "p0":"New York", - "p1":"2024-06-03T10:47:00.7880000Z", - "p2":"2024-06-06T10:47:00.7880000Z", - "p3":"companies/kitchenAppliances" -} -`} - - - - - - -## Register time series type - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `store.TimeSeries.Register`, e.g.: - - - -{`// Register the StockPrice class type on the server -store.TimeSeries.Register(); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view.png) -#### Syntax - - - -{`public void Register(string name = null) -`} - - - - -{`public void Register(string name, string[] valueNames) -`} - - - - -{`public void Register(string collection, string name, string[] valueNames) -`} - - - -
- -| Parameter | Type | Description | -|----------------------|------------------|-------------------------------------------------------------------------| -| **TCollection** | Collection type | The time series collection | -| **TTimeSeriesEntry** | Time series type | The custom time series type | -| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx deleted file mode 100644 index 7a6a805741..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_named-time-series-values-nodejs.mdx +++ /dev/null @@ -1,304 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. - Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. - -* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) - makes your code more readable and easier to manage. - -* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), - you need to register the named values on the server. - -* In this page: - * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) - * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) - * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) - * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) - * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) - * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) - - -## Named values - -* Many time series are populated with multiple values for each measurement. - For example, each GPS measurement in a route-tracking time series would include at least two values: - latitude and longitude. - -* You can ease the management of multi-value time series by - - * Naming time series values in custom classes. - * Calling time series methods with your custom types to address and manage values by name. -#### Define time series class with named values - -To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. -E.g.: - - - -{`class RoutePoint \{ - - // Add the following static param: - static TIME_SERIES_VALUES = ["latitude", "longitude"]; - - // The Latitude and Longitude properties will contain the time series entry values. - // The names for these values will be "latitude" and "longitude" respectively. - - constructor( - latitude = 0, - longitude = 0 - ) \{ - Object.assign(this, \{ - latitude, - longitude - \}); - \} -\} -`} - - - -The class can then be used by time series methods like _append_: - - - -{`const baseTime = new Date(); -const oneHour = 60 * 60 * 1000; -let nextHour = new Date(baseTime.getTime() + oneHour); - -const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); - -const routePoint = new RoutePoint(); -routePoint.latitude = 40.712776; -routePoint.longitude = -74.005974; - -// Append coordinates using the routePoint object -tsf.append(nextHour, routePoint, "devices/Navigator"); - -await session.saveChanges(); -`} - - -#### Examples - -* In this example, we define a StockPrice class and use it when appending StockPrice entries. - - -{`class StockPrice \{ - - // Define the names for the entry values - static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; - - constructor( - open = 0, - close = 0, - high = 0, - low = 0, - volume = 0 - ) \{ - Object.assign(this, \{ - open, - close, - high, - low, - volume - \}); - \} -\} -`} - - - - -{`const session = documentStore.openSession(); -await session.store(new User("John"), "users/john"); - -// Get an instance of 'timeSeriesFor', pass: -// * the document ID -// * the time series name -// * the class that will hold the entry's values -const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); - -const optionalTag = "companies/kitchenAppliances"; -const baseTime = new Date(); -baseTime.setUTCHours(0); -const oneDay = 24 * 60 * 60 * 1000; - -// Provide the multiple values via the StockPrice class -const price1 = new StockPrice(); -price1.open = 52; -price1.close = 54; -price1.high = 63.5; -price1.low = 51.4; -price1.volume = 9824; - -// Call 'append' with the custom StockPrice class -let nextDay = new Date(baseTime.getTime() + oneDay); -tsf.append(nextDay, price1, optionalTag); - -const price2 = new StockPrice(); -price2.open = 54; -price2.close = 55; -price2.high = 61.5; -price2.low = 49.4; -price2.volume = 8400; - -nextDay = new Date(baseTime.getTime() + oneDay * 2); -tsf.append(nextDay, price2, optionalTag); - -const price3 = new StockPrice(); -price3.open = 55; -price3.close = 57; -price3.high = 65.5; -price3.low = 50; -price3.volume = 9020; - -nextDay = new Date(baseTime.getTime() + oneDay * 3); -tsf.append(nextDay, price3, optionalTag); - -await session.saveChanges(); -`} - - - -* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. - - -{`let goingUp = false; - -const allEntries = await session - .timeSeriesFor("users/john", "StockPrices") - .get(); - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); - -// Access the entry value by its StockPrice class property name (close) -const closePriceDay1 = typedEntry1.value.close; - -const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); -const closePriceDay2 = typedEntry2.value.close; - -const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); -const closePriceDay3 = typedEntry3.value.close; - -// Check if the stock's closing price is rising -if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ - goingUp = true; -\} -`} - - - -* In this query, we use the custom StockPrice type so we can address trade Volume by name. - - - -{`const oneDay = 24 * 60 * 60 * 1000; -const startTime = new Date(); -const endTime = new Date(startTime.getTime() + 3 * oneDay); - -// Note: the 'where' clause must come after the 'between' clause -const tsQueryText = \` - from StockPrices - between $start and $end - where Tag == "AppleTech"\`; - -const query = session.query({ collection: "companies" }) - .whereEquals("address.city", "New York") - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .addParameter("start", startTime) - .addParameter("end", endTime); - -// Execute the query: -const results = await query.all(); - -// Access entries results: -const tsEntries = results[0].results; - -// Call 'asTypedEntry' to be able to access the entry's values by their names -// Pass the class type (StockPrice) -const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; -const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; -const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; -`} - - - - -{`from "companies" -where address.city = $p0 -select timeseries( - from StockPrices - between $start and $end - where Tag == "AppleTech") -{ - "p0":"New York", - "start":"2024-06-04T06:02:39.826Z", - "end":"2024-06-07T06:02:39.826Z" -} -`} - - - - - - -## Register time series named values - -Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). -This allows the Studio to present time series values by name when you view and manage them. -#### Usage - -To register a time series type, call `documentStore.timeSeries.register`, e.g.: - - - -{`// Register the named values for the 'StockPrices' series on the server -await documentStore.timeSeries.register("Users", - "StockPrices", ["open", "close", "high", "low", "volume"]); -`} - - - -
-The time series entries will be listed in the Studio under their corresponding named values: - -!["Time series entries"](./assets/time-series-entries-js.png) - -
-The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: - -!["Time series settings view"](./assets/time-series-settings-view-js.png) -#### Syntax - - - -{`// Available overloads: -// ==================== - -register(collection, name, valueNames); -register(collectionClass, name, valueNames); -register(collectionClass, timeSeriesEntryClass); -register(collectionClass, timeSeriesEntryClass, name); -`} - - - -
- -| Parameter | Type | Description | -|--------------------------|------------|------------------------------------| -| **collection** | `string` | The time series collection name | -| **name** | `string ` | Time series name | -| **valueNames** | `string[]` | Names to register (name per value) | -| **collectionClass** | `object` | The collection class | -| **timeSeriesEntryClass** | `object` | The custom time series entry class | - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx index 4c54a52e40..54b9fcffbd 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendInBulkCsharp from './_append-in-bulk-csharp.mdx'; -import AppendInBulkNodejs from './_append-in-bulk-nodejs.mdx'; +import AppendInBulkCsharp from './content/_append-in-bulk-csharp.mdx'; +import AppendInBulkNodejs from './content/_append-in-bulk-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/_append-in-bulk-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/bulk-insert/content/_append-in-bulk-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/_javascript-support-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_javascript-support-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/_javascript-support-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_javascript-support-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx new file mode 100644 index 0000000000..3e37fa11cf --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-csharp.mdx @@ -0,0 +1,268 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `Append`, `Get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the time series types on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-type) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series type](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-type) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in model classes that can be used as time series types. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series type + +To define a class for use as a time series type, mark the class properties (which represent the values) +with consecutive `TimeSeriesValue` attributes: `TimeSeriesValue(0)`, `TimeSeriesValue(1)`, etc. + +E.g.: + + + +{`public class RoutePoint +\{ + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "Latitude" and "Longitude" respectively. + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; +\} +`} + + + +The class can then be used by time series methods like _Append_: + + + +{`// Append coordinates +session.TimeSeriesFor("users/john") + .Append(baseTime.AddHours(1), new RoutePoint + \{ + Latitude = 40.712776, + Longitude = -74.005974 + \}, "devices/Navigator"); +`} + + + + +A quick way of retrieving a time series entry's value, timestamp, and tag is to use `Deconstruct()`: + + + +{`public void Deconstruct(out DateTime timestamp, out T value); +public void Deconstruct(out DateTime timestamp, out T value, out string tag); +`} + + + +#### Examples + +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + + +{`public class StockPrice +\{ + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; +\} +`} + + + + +{`using (var session = store.OpenSession()) +\{ + session.Store(new User \{ Name = "John" \}, "users/john"); + + // Call 'Append' with the custom StockPrice class + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(1), new StockPrice + \{ + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(2), new StockPrice + \{ + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + \}, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseTime.AddDays(3), new StockPrice + \{ + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + \}, "companies/kitchenAppliances"); + + session.SaveChanges(); +\} +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`goingUp = false; + +using (var session = store.OpenSession()) +\{ + // Call 'Get' with the custom StockPrice class type + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john") + .Get(); + + var closePriceDay1 = val[0].Value.Close; + var closePriceDay2 = val[1].Value.Close; + var closePriceDay3 = val[2].Value.Close; + + if ((closePriceDay2 > closePriceDay1) + && + (closePriceDay3 > closePriceDay2)) + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`using (var session = store.OpenSession()) +{ + var query = + session.Query() + .Where(c => c.Address.City == "New York") + // Use the StockPrice type in the time series query + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseTime, baseTime.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + + List> queryResults = query.ToList(); + + var tsEntries = queryResults[0].Results; + + double volumeDay1 = tsEntries[0].Value.Volume; + double volumeDay2 = tsEntries[1].Value.Volume; + double volumeDay3 = tsEntries[2].Value.Volume; +} +`} + + + + +{`from "companies" as c +where Address.City = $p0 +select timeseries( + from c.StockPrices + between $p1 and $p2 + where (Tag == $p3)) +{ + "p0":"New York", + "p1":"2024-06-03T10:47:00.7880000Z", + "p2":"2024-06-06T10:47:00.7880000Z", + "p3":"companies/kitchenAppliances" +} +`} + + + + + + +## Register time series type + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `store.TimeSeries.Register`, e.g.: + + + +{`// Register the StockPrice class type on the server +store.TimeSeries.Register(); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view.png) +#### Syntax + + + +{`public void Register(string name = null) +`} + + + + +{`public void Register(string name, string[] valueNames) +`} + + + + +{`public void Register(string collection, string name, string[] valueNames) +`} + + + +
+ +| Parameter | Type | Description | +|----------------------|------------------|-------------------------------------------------------------------------| +| **TCollection** | Collection type | The time series collection | +| **TTimeSeriesEntry** | Time series type | The custom time series type | +| **collection** | `string` | The time series collection name
(when `TCollection` is not provided) | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx new file mode 100644 index 0000000000..22ba4e78c4 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_named-time-series-values-nodejs.mdx @@ -0,0 +1,304 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A time series entry consists of a **timestamp**, one or more **values**, and an optional **tag**. + Each value can be given a name to indicate what it represents, such as "Temperature", "Humidity", "Pressure", etc. + +* Referring to these values by their names in time series methods (such as `append`, `get`, etc.) + makes your code more readable and easier to manage. + +* In order for the Studio to present the time series values by their names, as can be seen [here](../../../studio/database/document-extensions/time-series.mdx#time-series-view), + you need to register the named values on the server. + +* In this page: + * [Named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#named-values) + * [Define time series class with named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#define-time-series-class-with-named-values) + * [Examples](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#examples) + * [Register time series named values](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#register-time-series-named-values) + * [Usage](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#usage) + * [Syntax](../../../document-extensions/timeseries/client-api/named-time-series-values.mdx#syntax) + + +## Named values + +* Many time series are populated with multiple values for each measurement. + For example, each GPS measurement in a route-tracking time series would include at least two values: + latitude and longitude. + +* You can ease the management of multi-value time series by - + * Naming time series values in custom classes. + * Calling time series methods with your custom types to address and manage values by name. +#### Define time series class with named values + +To define a class with named values, add the static property `TIME_SERIES_VALUES` to the class. +E.g.: + + + +{`class RoutePoint \{ + + // Add the following static param: + static TIME_SERIES_VALUES = ["latitude", "longitude"]; + + // The Latitude and Longitude properties will contain the time series entry values. + // The names for these values will be "latitude" and "longitude" respectively. + + constructor( + latitude = 0, + longitude = 0 + ) \{ + Object.assign(this, \{ + latitude, + longitude + \}); + \} +\} +`} + + + +The class can then be used by time series methods like _append_: + + + +{`const baseTime = new Date(); +const oneHour = 60 * 60 * 1000; +let nextHour = new Date(baseTime.getTime() + oneHour); + +const tsf = session.timeSeriesFor("users/john", "RoutePoints", RoutePoint); + +const routePoint = new RoutePoint(); +routePoint.latitude = 40.712776; +routePoint.longitude = -74.005974; + +// Append coordinates using the routePoint object +tsf.append(nextHour, routePoint, "devices/Navigator"); + +await session.saveChanges(); +`} + + +#### Examples + +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + + +{`class StockPrice \{ + + // Define the names for the entry values + static TIME_SERIES_VALUES = ["open", "close", "high", "low", "volume"]; + + constructor( + open = 0, + close = 0, + high = 0, + low = 0, + volume = 0 + ) \{ + Object.assign(this, \{ + open, + close, + high, + low, + volume + \}); + \} +\} +`} + + + + +{`const session = documentStore.openSession(); +await session.store(new User("John"), "users/john"); + +// Get an instance of 'timeSeriesFor', pass: +// * the document ID +// * the time series name +// * the class that will hold the entry's values +const tsf = session.timeSeriesFor("users/john", "StockPrices", StockPrice); + +const optionalTag = "companies/kitchenAppliances"; +const baseTime = new Date(); +baseTime.setUTCHours(0); +const oneDay = 24 * 60 * 60 * 1000; + +// Provide the multiple values via the StockPrice class +const price1 = new StockPrice(); +price1.open = 52; +price1.close = 54; +price1.high = 63.5; +price1.low = 51.4; +price1.volume = 9824; + +// Call 'append' with the custom StockPrice class +let nextDay = new Date(baseTime.getTime() + oneDay); +tsf.append(nextDay, price1, optionalTag); + +const price2 = new StockPrice(); +price2.open = 54; +price2.close = 55; +price2.high = 61.5; +price2.low = 49.4; +price2.volume = 8400; + +nextDay = new Date(baseTime.getTime() + oneDay * 2); +tsf.append(nextDay, price2, optionalTag); + +const price3 = new StockPrice(); +price3.open = 55; +price3.close = 57; +price3.high = 65.5; +price3.low = 50; +price3.volume = 9020; + +nextDay = new Date(baseTime.getTime() + oneDay * 3); +tsf.append(nextDay, price3, optionalTag); + +await session.saveChanges(); +`} + + + +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + + +{`let goingUp = false; + +const allEntries = await session + .timeSeriesFor("users/john", "StockPrices") + .get(); + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const typedEntry1 = allEntries[0].asTypedEntry(StockPrice); + +// Access the entry value by its StockPrice class property name (close) +const closePriceDay1 = typedEntry1.value.close; + +const typedEntry2 = allEntries[1].asTypedEntry(StockPrice); +const closePriceDay2 = typedEntry2.value.close; + +const typedEntry3 = allEntries[2].asTypedEntry(StockPrice); +const closePriceDay3 = typedEntry3.value.close; + +// Check if the stock's closing price is rising +if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) \{ + goingUp = true; +\} +`} + + + +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + + + +{`const oneDay = 24 * 60 * 60 * 1000; +const startTime = new Date(); +const endTime = new Date(startTime.getTime() + 3 * oneDay); + +// Note: the 'where' clause must come after the 'between' clause +const tsQueryText = \` + from StockPrices + between $start and $end + where Tag == "AppleTech"\`; + +const query = session.query({ collection: "companies" }) + .whereEquals("address.city", "New York") + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .addParameter("start", startTime) + .addParameter("end", endTime); + +// Execute the query: +const results = await query.all(); + +// Access entries results: +const tsEntries = results[0].results; + +// Call 'asTypedEntry' to be able to access the entry's values by their names +// Pass the class type (StockPrice) +const volumeDay1 = tsEntries[0].asTypedEntry(StockPrice).value.volume; +const volumeDay2 = tsEntries[1].asTypedEntry(StockPrice).value.volume; +const volumeDay3 = tsEntries[2].asTypedEntry(StockPrice).value.volume; +`} + + + + +{`from "companies" +where address.city = $p0 +select timeseries( + from StockPrices + between $start and $end + where Tag == "AppleTech") +{ + "p0":"New York", + "start":"2024-06-04T06:02:39.826Z", + "end":"2024-06-07T06:02:39.826Z" +} +`} + + + + + + +## Register time series named values + +Registering a custom time series type on the server stores this information in the [database record](../../../studio/database/settings/database-record.mdx). +This allows the Studio to present time series values by name when you view and manage them. +#### Usage + +To register a time series type, call `documentStore.timeSeries.register`, e.g.: + + + +{`// Register the named values for the 'StockPrices' series on the server +await documentStore.timeSeries.register("Users", + "StockPrices", ["open", "close", "high", "low", "volume"]); +`} + + + +
+The time series entries will be listed in the Studio under their corresponding named values: + +!["Time series entries"](../assets/time-series-entries-js.png) + +
+The named values can be managed from the [Time Series Settings View](../../../studio/database/settings/time-series-settings.mdx) in the Studio: + +!["Time series settings view"](../assets/time-series-settings-view-js.png) +#### Syntax + + + +{`// Available overloads: +// ==================== + +register(collection, name, valueNames); +register(collectionClass, name, valueNames); +register(collectionClass, timeSeriesEntryClass); +register(collectionClass, timeSeriesEntryClass, name); +`} + + + +
+ +| Parameter | Type | Description | +|--------------------------|------------|------------------------------------| +| **collection** | `string` | The time series collection name | +| **name** | `string ` | Time series name | +| **valueNames** | `string[]` | Names to register (name per value) | +| **collectionClass** | `object` | The collection class | +| **timeSeriesEntryClass** | `object` | The custom time series entry class | + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/_overview-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/_overview-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/javascript-support.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/javascript-support.mdx index 4902155d9d..4309754c99 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/javascript-support.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/javascript-support.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptSupportCsharp from './_javascript-support-csharp.mdx'; -import JavascriptSupportNodejs from './_javascript-support-nodejs.mdx'; +import JavascriptSupportCsharp from './content/_javascript-support-csharp.mdx'; +import JavascriptSupportNodejs from './content/_javascript-support-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/named-time-series-values.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/named-time-series-values.mdx index 985088adc9..6527d69402 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/named-time-series-values.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/named-time-series-values.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NamedTimeSeriesValuesCsharp from './_named-time-series-values-csharp.mdx'; -import NamedTimeSeriesValuesNodejs from './_named-time-series-values-nodejs.mdx'; +import NamedTimeSeriesValuesCsharp from './content/_named-time-series-values-csharp.mdx'; +import NamedTimeSeriesValuesNodejs from './content/_named-time-series-values-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/append-and-delete.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/append-and-delete.mdx index 8183be1b83..0444ff8e48 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/append-and-delete.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/append-and-delete.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendAndDeleteCsharp from './_append-and-delete-csharp.mdx'; -import AppendAndDeleteNodejs from './_append-and-delete-nodejs.mdx'; +import AppendAndDeleteCsharp from './content/_append-and-delete-csharp.mdx'; +import AppendAndDeleteNodejs from './content/_append-and-delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_append-and-delete-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_append-and-delete-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_append-and-delete-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_append-and-delete-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_get-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_get-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_get-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_get-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_get-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_patch-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_patch-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/_patch-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/get.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/get.mdx index eab1c2ce26..3c14d3cb98 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/get.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/get.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetCsharp from './_get-csharp.mdx'; -import GetNodejs from './_get-nodejs.mdx'; +import GetCsharp from './content/_get-csharp.mdx'; +import GetNodejs from './content/_get-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/patch.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/patch.mdx index 64f49ff216..5ae6c43b3f 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/patch.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/operations/patch.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/overview.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/overview.mdx index dbffbe4b52..56a4d6aa5d 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/overview.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/append.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/append.mdx index 747898ca56..2601b2b3fa 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/append.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/append.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AppendCsharp from './_append-csharp.mdx'; -import AppendPython from './_append-python.mdx'; -import AppendPhp from './_append-php.mdx'; -import AppendNodejs from './_append-nodejs.mdx'; +import AppendCsharp from './content/_append-csharp.mdx'; +import AppendPython from './content/_append-python.mdx'; +import AppendPhp from './content/_append-php.mdx'; +import AppendNodejs from './content/_append-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_append-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_append-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_delete-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_delete-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_patch-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_patch-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_querying-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_querying-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_querying-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/_querying-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/content/_querying-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/delete.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/delete.mdx index 9864f84337..964df21533 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/delete.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/delete.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCsharp from './_delete-csharp.mdx'; -import DeletePython from './_delete-python.mdx'; -import DeletePhp from './_delete-php.mdx'; -import DeleteNodejs from './_delete-nodejs.mdx'; +import DeleteCsharp from './content/_delete-csharp.mdx'; +import DeletePython from './content/_delete-python.mdx'; +import DeletePhp from './content/_delete-php.mdx'; +import DeleteNodejs from './content/_delete-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-entries-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-entries-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/_get-names-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/content/_get-names-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-entries.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-entries.mdx index 84749e4d5e..11f2b02aec 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-entries.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-entries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetEntriesCsharp from './_get-entries-csharp.mdx'; -import GetEntriesPython from './_get-entries-python.mdx'; -import GetEntriesPhp from './_get-entries-php.mdx'; -import GetEntriesNodejs from './_get-entries-nodejs.mdx'; +import GetEntriesCsharp from './content/_get-entries-csharp.mdx'; +import GetEntriesPython from './content/_get-entries-python.mdx'; +import GetEntriesPhp from './content/_get-entries-php.mdx'; +import GetEntriesNodejs from './content/_get-entries-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-names.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-names.mdx index 458750c71f..e56f23ce80 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-names.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/get/get-names.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GetNamesCsharp from './_get-names-csharp.mdx'; -import GetNamesPython from './_get-names-python.mdx'; -import GetNamesPhp from './_get-names-php.mdx'; -import GetNamesNodejs from './_get-names-nodejs.mdx'; +import GetNamesCsharp from './content/_get-names-csharp.mdx'; +import GetNamesPython from './content/_get-names-python.mdx'; +import GetNamesPhp from './content/_get-names-php.mdx'; +import GetNamesNodejs from './content/_get-names-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_overview-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_overview-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_overview-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_overview-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-raw-queries-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-raw-queries-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-raw-queries-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-load-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-load-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-load-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-load-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-query-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-query-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/_with-session-query-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/content/_with-session-query-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/overview.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/overview.mdx index 49621fc34a..ca2423063c 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/overview.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx index bc058d3c10..dba68884ab 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-raw-queries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithRawQueriesCsharp from './_with-raw-queries-csharp.mdx'; -import WithRawQueriesNodejs from './_with-raw-queries-nodejs.mdx'; +import WithRawQueriesCsharp from './content/_with-raw-queries-csharp.mdx'; +import WithRawQueriesNodejs from './content/_with-raw-queries-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-load.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-load.mdx index e14d8c0fb0..50fa25c57a 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-load.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-load.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionLoadCsharp from './_with-session-load-csharp.mdx'; -import WithSessionLoadNodejs from './_with-session-load-nodejs.mdx'; +import WithSessionLoadCsharp from './content/_with-session-load-csharp.mdx'; +import WithSessionLoadNodejs from './content/_with-session-load-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-query.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-query.mdx index 04f1dac6f3..e6e39fcc36 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-query.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/include/with-session-query.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WithSessionQueryCsharp from './_with-session-query-csharp.mdx'; -import WithSessionQueryNodejs from './_with-session-query-nodejs.mdx'; +import WithSessionQueryCsharp from './content/_with-session-query-csharp.mdx'; +import WithSessionQueryNodejs from './content/_with-session-query-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/patch.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/patch.mdx index 68a6d9c826..58d578b97f 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/patch.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/patch.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCsharp from './_patch-csharp.mdx'; -import PatchPython from './_patch-python.mdx'; -import PatchPhp from './_patch-php.mdx'; -import PatchNodejs from './_patch-nodejs.mdx'; +import PatchCsharp from './content/_patch-csharp.mdx'; +import PatchPython from './content/_patch-python.mdx'; +import PatchPhp from './content/_patch-php.mdx'; +import PatchNodejs from './content/_patch-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/querying.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/querying.mdx index e41bfd2a84..2d84e8f2ff 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/querying.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/client-api/session/querying.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryingCsharp from './_querying-csharp.mdx'; -import QueryingNodejs from './_querying-nodejs.mdx'; +import QueryingCsharp from './content/_querying-csharp.mdx'; +import QueryingNodejs from './content/_querying-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_design-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_design-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_design-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_design-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_design-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_design-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_design-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_design-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_indexing-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_indexing-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_indexing-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_indexing-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_indexing-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_indexing-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/_indexing-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/_indexing-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/content/_indexing-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx new file mode 100644 index 0000000000..c0d3e3b2c5 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-csharp.mdx @@ -0,0 +1,300 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`var oneWeek = TimeValue.FromDays(7); +var fiveYears = TimeValue.FromYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +var rawPolicy = new RawTimeSeriesPolicy(fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +var rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + oneWeek, // Aggregation time, roll-up the data for each week + fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +var timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.Collections["Companies"] = new TimeSeriesCollectionConfiguration +\{ + Policies = new List \{ rollupPolicy \}, + RawPolicy = rawPolicy +\}; + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +store.Maintenance.Send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +var rawData = session + .TimeSeriesFor("companies/91-A", "StockPrices") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +var rollupData = session + .TimeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .Get(DateTime.MinValue, DateTime.MaxValue); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = session + .TimeSeriesFor("companies/91-A", rollupPolicy.GetTimeSeriesName("StockPrices")) + .Get(DateTime.MinValue, DateTime.MaxValue); + +// The raw time series has 100 entries +Assert.Equal(rawData.Length, 100); +Assert.Equal(rawData[0].IsRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +Assert.Equal(rollupData.Length, 22); +Assert.Equal(rollupData[0].IsRollup, true); +`} + + + + + +## Syntax + +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`public class RawTimeSeriesPolicy : TimeSeriesPolicy +\{ + public TimeValue RetentionTime; +\} + +public class TimeSeriesPolicy +\{ + public string Name; + public TimeValue RetentionTime; \{ get; protected set; \} + public TimeValue AggregationTime; \{ get; private set; \} +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **RetentionTime** | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| **AggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`public struct TimeValue +\{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +\} +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`public class TimeSeriesConfiguration +\{ + public Dictionary Collections; +\} + +public class TimeSeriesCollectionConfiguration +\{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +\} +`} + + + +| Property | Description | +|-----------------|---------------------------------------------------------------------------------------------------------------------------| +| **Collections** | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **Disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **Policies** | Populate this `List` with your rollup policies. | +| **RawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Casting time series entries + +Time series entries are of one of the following classes: + + + +{`public class TimeSeriesEntry \{ \} +public class TimeSeriesEntry : TimeSeriesEntry \{ \} +public class TimeSeriesRollupEntry : TimeSeriesEntry \{ \} +`} + + + +If you have an existing rollup entry of type `TimeSeriesEntry`, +you can cast it to a `TimeSeriesRollupEntry` using `AsRollupEntry()`. + + + +{`public static TimeSeriesRollupEntry AsRollupEntry(this TimeSeriesEntry entry); +`} + + + +You can cast a `TimeSeriesRollupEntry` to a `TimeSeriesEntry` directly. +Its values will consist of all the `First` values of the rollup entry. + + + +{`var rollupEntry = new TimeSeriesRollupEntry(new DateTime(2020,1,1)); +TimeSeriesEntry TSEntry = (TimeSeriesEntry)rollupEntry; +`} + + + +Read more about time series with generic types [here](../../document-extensions/timeseries/client-api/named-time-series-values.mdx). + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx new file mode 100644 index 0000000000..57c5f44e40 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-nodejs.mdx @@ -0,0 +1,257 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* *First* - the value of the first entry in the frame. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the frame. +* *Count* - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`// Define a policy on the RAW time series data: +// ============================================ +const rawPolicy = new RawTimeSeriesPolicy(TimeValue.ofYears(5)); // Retain data for five years + +// Define a ROLLUP policy: +// ======================= +const rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + TimeValue.ofDays(7), // Aggregation time, roll-up the data for each week + TimeValue.ofYears(5)); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +const collectionConfig = new TimeSeriesCollectionConfiguration(); +collectionConfig.rawPolicy = rawPolicy; +collectionConfig.policies = [rollupPolicy]; + +const timeSeriesConfig = new TimeSeriesConfiguration(); +timeSeriesConfig.collections.set("Companies", collectionConfig); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +await documentStore.maintenance.send(new ConfigureTimeSeriesOperation(timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +const rawData = await session + .timeSeriesFor("companies/91-A", "StockPrices") + .get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +let rollupData = await session + .timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + .get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +rollupData = await session + .timeSeriesFor("companies/91-A", rollupPolicy.getTimeSeriesName("StockPrices")) + .get(); + +// The raw time series has 100 entries +assert.equal(rawData.length, 100); +assert.equal(rawData[0].isRollup, false); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +assert.equal(rollupData.length, 22); +assert.equal(rollupData[0].isRollup, true); +`} + + + + + +## Syntax +### The time series policies + +* Raw policy: + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy extends TimeSeriesPolicy \{ + retentionTime; // TimeValue +\} + +class TimeSeriesPolicy \{ + name; // string; + retentionTime // TimeValue + aggregationTime // TimeValue +\} +`} + + + +| Property | Description | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | This string is used to create the name of the rollup time series.
`Name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retentionTime** | Time series entries older than this `TimeValue` are automatically deleted. | +| **aggregationTime** | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue \{ + static ofSeconds(seconds); + static ofMinutes(minutes); + static ofHours(hours); + static ofDays(days); + static ofMonths(months); + static ofYears(years); +\} +`} + + + + +The main reason we use `TimeValue` rather than something like `TimeSpan` is that `TimeSpan` doesn't have a notion of 'months' +because a calendar month is not a standard unit of time (as it can range from 28 to 31 days). +`TimeValue` enables you to define retention and aggregation spans specifically tailored to calendar months. + +### The time series configuration object + + + +{`class TimeSeriesConfiguration \{ + collections; // Map +\} + +class TimeSeriesCollectionConfiguration \{ + disabled; // boolean + policies; // TimeSeriesPolicy[] + rawPolicy; // RawTimeSeriesPolicy +\} +`} + + + +| Property | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------| +| **collections** | Populate this dictionary with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** | Populate this list with your rollup policies. | +| **rawPolicy** | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`ConfigureTimeSeriesOperation(configuration); +`} + + + +| Parameter | Description | +|-------------------|--------------------------------------------------------------| +| **configuration** | The `TimeSeriesConfiguration` object to deploy to the server | + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-php.mdx new file mode 100644 index 0000000000..7da93ce29a --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-php.mdx @@ -0,0 +1,334 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx#examples) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`$oneWeek = TimeValue::ofDays(7); +$fiveYears = TimeValue::ofYears(5); + +// Define a policy on the RAW time series data: +// ============================================ +$rawPolicy = new RawTimeSeriesPolicy($fiveYears); // Retain entries for five years + +// Define a ROLLUP policy: +// ======================= +$rollupPolicy = new TimeSeriesPolicy( + "By1WeekFor1Year", // Name of policy + $oneWeek, // Aggregation time, roll-up the data for each week + $fiveYears); // Retention time, keep data for five years + +// Define the time series configuration for collection "Companies" (use above policies): +// ===================================================================================== +$companyConfig = new TimeSeriesCollectionConfiguration(); +$companyConfig->setPolicies(TimeSeriesPolicyArray::fromArray([ $rollupPolicy ])); +$companyConfig->setRawPolicy($rawPolicy); + +$timeSeriesConfig = new TimeSeriesConfiguration(); +$timeSeriesConfig->setCollections([ + "Companies" => $companyConfig +]); + +// Deploy the time series configuration to the server +// by sending the 'ConfigureTimeSeriesOperation' operation: +// ======================================================== +$store->maintenance()->send(new ConfigureTimeSeriesOperation($timeSeriesConfig)); + +// NOTE: +// The time series entries in the RavenDB sample data are dated up to the year 2020. +// To ensure that you see the rollup time series created when running this example, +// the retention time should be set to exceed that year. +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`// Get all data from the RAW time series: +// ====================================== + +$rawData = $session + ->timeSeriesFor("companies/91-A", "StockPrices") + ->get(); + +// Get all data from the ROLLUP time series: +// ========================================= + +// Either - pass the rollup name explicitly to 'TimeSeriesFor': +$rollupData = $session + ->timeSeriesFor("companies/91-A", "StockPrices@By1WeekFor1Year") + ->get(); + +// Or - get the rollup name by calling 'GetTimeSeriesName': +$rollupData = $session + ->timeSeriesFor("companies/91-A", $rollupPolicy->GetTimeSeriesName("StockPrices")) + ->get(); + +// The raw time series has 100 entries +$this->assertCount(100, $rawData); +$this->assertFalse($rawData[0]->isRollup()); + +// The rollup time series has only 22 entries +// as each entry aggregates 1 week's data from the raw time series +$this->assertCount(22, $rollupData); +$this->assertTrue($rollupData[0]->isRollup()); +`} + + + + + +## Syntax + +### The time series policies + +* `rawPolicy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|--------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-python.mdx new file mode 100644 index 0000000000..5d3e24fd7f --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_rollup-and-retention-python.mdx @@ -0,0 +1,309 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention.mdx#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention.mdx#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention.mdx#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention.mdx#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention.mdx#syntax) + + +## Time series policies + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](../assets/rollup-1.png) + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + + + +## Examples + +#### Create time series policies: + + + +{`# Policy for the original ("raw") time-series, +# to keep the data for one week +one_week = TimeValue.of_days(7) +raw_retention = RawTimeSeriesPolicy(one_week) + +# Roll-up the data for each day, +# and keep the results for one year +one_day = TimeValue.of_days(1) +one_year = TimeValue.of_years(1) +daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + +# Enter the above policies into a +# time-series collection configuration +# for the collection 'Sales' +sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + +# Enter the configuration for the Sales collection +# into a time-series configuration for the whole database +database_ts_config = TimeSeriesConfiguration() +database_ts_config.collections["Sales"] = sales_ts_config + +# Send the time-series configuration to the server +store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) +`} + + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries.mdx). + + + +{`# Create local instance of the time-series "rawSales" +# in the document "sales/1" +raw_ts = session.time_series_for("sales/1", "rawSales") + +# Create local instance of the rollup time-series - first method: +daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + +# Create local instance of the rollup time-series - second method: +# using the rollup policy itself and the raw time-series' name +rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + +# Retrieve all the data from both time-series +raw_data = raw_ts.get(datetime.min, datetime.max) +rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) +`} + + + + + +## Syntax + +### The time series policies + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + + + +{`class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +`} + + + +| Property | Type | Description | +|----------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` | The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + + + +{`class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +`} + + + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. +### The time series configuration object + + + +{`class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = \{\} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +`} + + + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | +### The time series configuration operation + + + +{`class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +`} + + + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations.mdx). +### Time series entries + +Time series entries are of one of the following classes: + + + +{`class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx new file mode 100644 index 0000000000..1bb2e3c42c --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-csharp.mdx @@ -0,0 +1,115 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the parameter `DatabaseItemType.TimeSeries` to the `OperateOnTypes` enum property: + + + +{`OperateOnTypes = DatabaseItemType.Documents | DatabaseItemType.TimeSeries +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx new file mode 100644 index 0000000000..ca52726064 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/content/_time-series-and-other-features-nodejs.mdx @@ -0,0 +1,116 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* This page describes how time series interact with various other RavenDB features. + +* Features not listed here either have no special behavior regarding time series, + or they have their own pages describing their interaction with time series (such as [indexing](../../document-extensions/timeseries/indexing.mdx)). + +* In this page: + * [General features](../../document-extensions/timeseries/time-series-and-other-features.mdx#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features.mdx#smuggler) + * [Ongoing tasks](../../document-extensions/timeseries/time-series-and-other-features.mdx#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features.mdx#revisions) + + +## General features + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work.mdx#tracking-changes) changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api.mdx) service is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing.mdx). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax.mdx). +* Learn how to **include** time series with `session.Load()` and in queries [here](../../document-extensions/timeseries/client-api/session/include/overview.mdx). + + + +## Smuggler + +[Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) is a DocumentStore property that can be used to export selected database items to an external file +or import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler.mdx#databasesmugglerexportoptions) to handle time series, +add the string `TimeSeries` to the `operateOnTypes` array: + + + +{`const options = new DatabaseSmugglerExportOptions(); +options.operateOnTypes = ["Documents", "TimeSeries"]; +`} + + + + + +## Ongoing tasks + +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info.mdx) are various automatic processes that operate on the database. +Some of these apply to time series data, while others do not. + +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication.mdx) creates a complete copy of a database, including documents and their extensions. +* [Hub/Sink replication](../../server/ongoing-tasks/hub-sink-replication.mdx) allows you to create a live replica of a database or a part of it, + including documents' time series, using Hub and Sink tasks. +* [Backups](../../client-api/operations/maintenance/backup/backup-overview.mdx) save the whole database at a certain point in time and can be used to restore the database later. + All kinds of backups include time series data: logical-backup and snapshot, full and incremental. +* [RavenDB ETL](../../server/ongoing-tasks/etl/raven.mdx#time-series) is a type of task that _extracts_ some portion of the data from a database, _transforms_ it according to a script, + and _loads_ it to another RavenDB database on another server. + +#### Tasks that cannot be applied to time series + +* [SQL ETL](../../server/ongoing-tasks/etl/basics.mdx), another type of ETL that can set a relational database as its target. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) send data to "worker" clients in batches. + + + +Support for time series in ETL is planned for one of the next releases. + + + + + +## Revisions + +[Revisions](../../document-extensions/revisions/overview.mdx) are old versions of a document. +They can be created manually or by setting a policy that creates them automatically on selected collections. + +Revisions do not preserve time series data, and editing a time series does not trigger the creation of a new revision as editing a document would. +This is because time series are designed to accommodate frequent additions of new entries quickly, and creating revisions each time would significantly slow down this process. + +However, revisions are triggered / created manually if a _new_ time series is added to the document, +or an existing time series is deleted. (Remember that a time series is deleted by deleting all of its entries). + +#### The `@timeseries-snapshot` metadata property + +While revisions don't contain the time series data themselves, they do include few details about the time series the document had at the time. +These details appear in the `@timeseries-snapshot` property within the document's metadata. +When a revision is viewed in the studio, this metadata property looks like this: + +![NoSQL Database Time Series Feature](../assets/TSSnapshot.png) + +This time series snapshot property can also be accessed by loading a revision in the client. +This is the general JSON format of the time series snapshot: + + + +{`"@metadata": \{ + ... + "@timeseries-snapshot": \{ + "": \{ + "Count": , + "Start": "", + "End": "" + \}, + "": \{ ... \} + \} +`} + + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/design.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/design.mdx index dc7e0e8ef9..930eac5768 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/design.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/design.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DesignCsharp from './_design-csharp.mdx'; -import DesignNodejs from './_design-nodejs.mdx'; +import DesignCsharp from './content/_design-csharp.mdx'; +import DesignNodejs from './content/_design-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/indexing.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/indexing.mdx index c7df4e6dfd..f9b1f74b04 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/indexing.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/indexing.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingCsharp from './_indexing-csharp.mdx'; -import IndexingPython from './_indexing-python.mdx'; -import IndexingPhp from './_indexing-php.mdx'; -import IndexingNodejs from './_indexing-nodejs.mdx'; +import IndexingCsharp from './content/_indexing-csharp.mdx'; +import IndexingPython from './content/_indexing-python.mdx'; +import IndexingPhp from './content/_indexing-php.mdx'; +import IndexingNodejs from './content/_indexing-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx deleted file mode 100644 index 18ae9a014f..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-csharp.mdx +++ /dev/null @@ -1,313 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - - -{`var query = from user in session.Query() - - // The custom function - let customFunc = new Func, IEnumerable>( - entries => - entries.Select(e => new ModifiedTimeSeriesEntry - { - Timestamp = e.Timestamp, - Value = e.Values.Max(), - Tag = e.Tag ?? "none" - })) - - // The time series query - let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") - .Where(entry => entry.Values[0] > 100) - .ToList() - - // Project query results - select new - { - Name = user.Name, - // Call the custom function - TimeSeriesEntries = customFunc(tsQuery.Results) - }; - -var queryResults = query.ToList(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`private class ModifiedTimeSeriesEntry -\{ - public DateTime Timestamp \{ get; set; \} - public double Value \{ get; set; \} - public string Tag \{ get; set; \} -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx deleted file mode 100644 index 3c635a3470..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-nodejs.mdx +++ /dev/null @@ -1,333 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Time series querying is native to RavenDB's queries. - Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using **high level queries**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - - -{`// Define the time series query text -const tsQueryText = "from HeartRates"; - -// Make a dynamic query over the "employees" collection -const queryResults = await session.query({ collection: "employees" }) - // Query for employees hired after 1994 - .whereGreaterThan("HiredAt", "1994-01-01") - // Call 'selectTimeSeries' to project the time series entries in the query results - // Pass the defined time series query text - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// Results: -// ======== - -// 1. Results will include all entries from time series "HeartRates" for matching employee documents. -// 2. Since this is a dynamic query that filters documents, -// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. -// However, it is NOT a time series index !! -// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. - -// Access a time series entry value from the results: -const entryValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "employees" as e -where HiredAt > "1994-01-01" -select timeseries ( - from HeartRates -) -`} - - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. -#### Example: - - - - -{`// Add 'scale ' to your time series query text -const tsQueryText = "from HeartRates scale 10"; - -const queryResults = await session.query({ collection: "users" }) - .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) - .all(); - -// The value in the query results is 10 times the value stored on the server -const scaledValue = queryResults[0].results[0].values[0]; -`} - - - - -{`from "users" -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - - - - -{`const queryResults = await session.advanced - // Provide RQL to rawQuery - .rawQuery(\` - // The time series function: - // ========================= - declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100) - } - - // The custom JavaScript function: - // =============================== - declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; - } - - // Query & project results: - // ======================== - from "users" as user - select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function - \`) - // Execute the query - .all(); -`} - - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) { - from user.HeartRates - where (Values[0] > 100.0) -} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) { - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) { - results.push({ - timestamp: r.Results[i].Timestamp, - value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - tag: r.Results[i].Tag ?? "none"}) - } - return results; -} - -// Query & project results: -// ======================== -from "users" as user -select - user.name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx deleted file mode 100644 index cb160b6ec6..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-php.mdx +++ /dev/null @@ -1,282 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry -\{ - private ?DateTime $timestamp = null; - private ?float $value = null; - private ?string $tag = null; - - // ... getters and setters ... -\} -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx deleted file mode 100644 index 2025bccf4a..0000000000 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_overview-and-syntax-python.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. - -* Querying time series data is native to RavenDB's queries. - Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). - -* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). - -* In this page: - * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) - * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) - * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) - * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) - * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) - * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) - * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) - * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) - * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) - - -## Time series query capabilities - -Time series query can - - -* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. -* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. -* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, - e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. - Entries can also be aggregated by their tags. -* Select entries by various criteria, e.g. by the min and max values of each aggregated group, - and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. -* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. - - - -## Server and client queries - -Time series queries are executed by the server and their results are projected to the client, -so they require very little client computation resources. - -* The server runs time series queries using RQL. -* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. - High level queries are translated to RQL by the client before sending them to the server for execution. - - - -## Dynamic and index queries - -* **Dynamic queries**: - * Time series indexes are Not created automatically by the server when making a dynamic query. - * Use dynamic queries when time series you query are not indexed, - or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). - E.g. - - - - -{`// Query for time series named "HeartRates" in employees hired after 1994 -from Employees as e -where HiredAt > "1994-01-01" -select timeseries( - from HeartRates -) -`} - - - -* **Index queries**: - * Static time series indexes can be created by clients (or using Studio). - To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). - * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). - - - -## Scaling query results - -* Time series query results can be **scaled**, multiplied by some number. - This doesn't change the values themselves, only the output of the query. - Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. - -* There are several use cases for scaling. - For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, - with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. - -* Another use case involves the compression of time series data. - Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. - Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. - Then, when querying the data, you can scale by `0.000001` to restore the original value. - -* Scaling is a part of both RQL and LINQ syntax: - - * In **LINQ**, use `.Scale()`. - * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. -#### Example: - - - - -{`var query = session.Query() - .Select(p => RavenQuery.TimeSeries(p, "HeartRates") - .Scale(10) - .ToList()) - .ToList(); - -// The value in the query results is 10 times the value stored on the server -var scaledValue = query[0].Results[0].Values[0]; -`} - - - - -{`from Users -select timeseries( - from HeartRates - scale 10 -) -`} - - - - - - -## RQL syntax - -A typical time series query can start by locating the documents whose time series we want to query. -For example, we can query for employees above 30: - - - -{`from Employees as e -where Birthday < '1994-01-01' -`} - - - -Then, you can query their time series entries using either of the following two equivalent syntaxes: - -* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) -* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) -### `select timeseries` - -This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. - - - -{`// Query for entries from time series "HeartRates" for employees above 30 -// ====================================================================== - -// This clause locates the documents whose time series we want to query: -from Employees as e -where Birthday < '1994-01-01' - -// Query the time series that belong to the matching documents: -select timeseries ( // The \`select\` clause defines the time series query. - from HeartRates // The \`from\` keyword is used to specify the time series name to query. -) -`} - - - -### `declare timeseries` - -This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. -It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. - -Here is a query written in both syntaxes. -It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. - -#### With Time Series Function - -```sql -// declare the time series function: -declare timeseries ts(jogger) { - from jogger.HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z" -} - -from Users as jogger -where Age > 30 -// call the time series function -select ts(jogger) -``` - -#### Without Time Series Function - -```sql -from Users as jogger -where Age > 30 -select timeseries( - from HeartRates - between - "2020-05-27T00:00:00.0000000Z" - and - "2020-06-23T00:00:00.0000000Z") -``` - -## Combine time series and custom functions - -* You can declare and use both time series functions and custom functions in a query. - The custom functions can call the time series functions, pass them arguments, and use their results. - -* In the example below, a custom function (`customFunc`) is called by the query `select` clause - to fetch and format a set of time series entries, which are then projected by the query. - The time series function (`tsQuery`) is called to retrieve the matching time series entries. - -* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. - -* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). - - - -{`// The time series function: -// ========================= -declare timeseries tsQuery(user) \{ - from user.HeartRates - where (Values[0] > 100) -\} - -// The custom JavaScript function: -// =============================== -declare function customFunc(user) \{ - var results = []; - - // Call the time series function to retrieve heart rate values for the user - var r = tsQuery(user); - - // Prepare the results - for(var i = 0 ; i < r.Results.length; i ++) \{ - results.push(\{ - Timestamp: r.Results[i].Timestamp, - Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), - Tag: r.Results[i].Tag ?? "none"\}) - \} - return results; -\} - -// Query & project results: -// ======================== -from "Users" as user -select - user.Name, - customFunc(user) as timeSeriesEntries // Call the custom JavaScript function -`} - - - -This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: - - - -{`class ModifiedTimeSeriesEntry: - def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): - self.timestamp = timestamp - self.value = value - self.tag = tag -`} - - - - - -## Use Studio to experiment - -You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. - -!["Time Series Query in Studio"](./assets/time-series-query.png) - - - - - diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/aggregation-and-projections.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/aggregation-and-projections.mdx index 7daddefac1..776e264522 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/aggregation-and-projections.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/aggregation-and-projections.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import AggregationAndProjectionsCsharp from './_aggregation-and-projections-csharp.mdx'; -import AggregationAndProjectionsPhp from './_aggregation-and-projections-php.mdx'; -import AggregationAndProjectionsNodejs from './_aggregation-and-projections-nodejs.mdx'; +import AggregationAndProjectionsCsharp from './content/_aggregation-and-projections-csharp.mdx'; +import AggregationAndProjectionsPhp from './content/_aggregation-and-projections-php.mdx'; +import AggregationAndProjectionsNodejs from './content/_aggregation-and-projections-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/choosing-query-range.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/choosing-query-range.mdx index 5509b95c69..95e4e2ec41 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/choosing-query-range.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/choosing-query-range.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ChoosingQueryRangeCsharp from './_choosing-query-range-csharp.mdx'; -import ChoosingQueryRangePython from './_choosing-query-range-python.mdx'; -import ChoosingQueryRangePhp from './_choosing-query-range-php.mdx'; -import ChoosingQueryRangeNodejs from './_choosing-query-range-nodejs.mdx'; +import ChoosingQueryRangeCsharp from './content/_choosing-query-range-csharp.mdx'; +import ChoosingQueryRangePython from './content/_choosing-query-range-python.mdx'; +import ChoosingQueryRangePhp from './content/_choosing-query-range-php.mdx'; +import ChoosingQueryRangeNodejs from './content/_choosing-query-range-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_aggregation-and-projections-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_aggregation-and-projections-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_choosing-query-range-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_choosing-query-range-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_filtering-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-java.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-java.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_gap-filling-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_gap-filling-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx new file mode 100644 index 0000000000..1b0383ae1e --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-csharp.mdx @@ -0,0 +1,313 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](../../../document-extensions/timeseries/indexing.mdx). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL in the second tab, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + + +{`var query = from user in session.Query() + + // The custom function + let customFunc = new Func, IEnumerable>( + entries => + entries.Select(e => new ModifiedTimeSeriesEntry + { + Timestamp = e.Timestamp, + Value = e.Values.Max(), + Tag = e.Tag ?? "none" + })) + + // The time series query + let tsQuery = RavenQuery.TimeSeries(user, "HeartRates") + .Where(entry => entry.Values[0] > 100) + .ToList() + + // Project query results + select new + { + Name = user.Name, + // Call the custom function + TimeSeriesEntries = customFunc(tsQuery.Results) + }; + +var queryResults = query.ToList(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`private class ModifiedTimeSeriesEntry +\{ + public DateTime Timestamp \{ get; set; \} + public double Value \{ get; set; \} + public string Tag \{ get; set; \} +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx new file mode 100644 index 0000000000..d4b5203c2b --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-nodejs.mdx @@ -0,0 +1,333 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Time series querying is native to RavenDB's queries. + Clients can express time series queries in high-level queries or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using **high level queries**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + + +{`// Define the time series query text +const tsQueryText = "from HeartRates"; + +// Make a dynamic query over the "employees" collection +const queryResults = await session.query({ collection: "employees" }) + // Query for employees hired after 1994 + .whereGreaterThan("HiredAt", "1994-01-01") + // Call 'selectTimeSeries' to project the time series entries in the query results + // Pass the defined time series query text + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// Results: +// ======== + +// 1. Results will include all entries from time series "HeartRates" for matching employee documents. +// 2. Since this is a dynamic query that filters documents, +// an auto-index (Auto/employees/ByHiredAt) will be created if it doesn't already exist. +// However, it is NOT a time series index !! +// It is a regular documents auto-index that allows querying for documents based on their HiredAt field. + +// Access a time series entry value from the results: +const entryValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "employees" as e +where HiredAt > "1994-01-01" +select timeseries ( + from HeartRates +) +`} + + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. +#### Example: + + + + +{`// Add 'scale ' to your time series query text +const tsQueryText = "from HeartRates scale 10"; + +const queryResults = await session.query({ collection: "users" }) + .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult) + .all(); + +// The value in the query results is 10 times the value stored on the server +const scaledValue = queryResults[0].results[0].values[0]; +`} + + + + +{`from "users" +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare) in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + + + + +{`const queryResults = await session.advanced + // Provide RQL to rawQuery + .rawQuery(\` + // The time series function: + // ========================= + declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) + } + + // The custom JavaScript function: + // =============================== + declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; + } + + // Query & project results: + // ======================== + from "users" as user + select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function + \`) + // Execute the query + .all(); +`} + + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100.0) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + timestamp: r.Results[i].Timestamp, + value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "users" as user +select + user.name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx new file mode 100644 index 0000000000..76bcc0b26c --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-php.mdx @@ -0,0 +1,282 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry +\{ + private ?DateTime $timestamp = null; + private ?float $value = null; + private ?string $tag = null; + + // ... getters and setters ... +\} +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx new file mode 100644 index 0000000000..11bb66c408 --- /dev/null +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_overview-and-syntax-python.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql.mdx). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing.mdx). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#use-studio-to-experiment) + + +## Time series query capabilities + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range.mdx) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering.mdx) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections.mdx) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics.mdx): the percentile, slope, or standard deviation of a time series. + + + +## Server and client queries + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + + + +## Dynamic and index queries + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). + E.g. - + + + +{`// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) +`} + + + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes.mdx). + + + +## Scaling query results + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. +#### Example: + + + + +{`var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +`} + + + + +{`from Users +select timeseries( + from HeartRates + scale 10 +) +`} + + + + + + +## RQL syntax + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + + + +{`from Employees as e +where Birthday < '1994-01-01' +`} + + + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax.mdx#section-1) +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + + + +{`// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The \`select\` clause defines the time series query. + from HeartRates // The \`from\` keyword is used to specify the time series name to query. +) +`} + + + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +#### With Time Series Function + +```sql +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +``` + +#### Without Time Series Function + +```sql +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") +``` + +## Combine time series and custom functions + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql.mdx#declare). + + + +{`// The time series function: +// ========================= +declare timeseries tsQuery(user) \{ + from user.HeartRates + where (Values[0] > 100) +\} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) \{ + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) \{ + results.push(\{ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"\}) + \} + return results; +\} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +`} + + + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + + + +{`class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag +`} + + + + + +## Use Studio to experiment + +You can use [Studio](../../../studio/database/document-extensions/time-series.mdx) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](../assets/time-series-query.png) + + + + + diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_stream-timeseries-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_stream-timeseries-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_stream-timeseries-java.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_stream-timeseries-java.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_stream-timeseries-java.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-csharp.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-csharp.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-nodejs.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-php.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-php.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-php.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-python.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/document-extensions/timeseries/querying/_using-indexes-python.mdx rename to versioned_docs/version-7.1/document-extensions/timeseries/querying/content/_using-indexes-python.mdx diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/filtering.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/filtering.mdx index 5904dc9d8b..86323f6277 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/filtering.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/filtering.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/gap-filling.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/gap-filling.mdx index 8886407b31..db04ec8e54 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/gap-filling.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/gap-filling.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import GapFillingCsharp from './_gap-filling-csharp.mdx'; -import GapFillingJava from './_gap-filling-java.mdx'; -import GapFillingNodejs from './_gap-filling-nodejs.mdx'; +import GapFillingCsharp from './content/_gap-filling-csharp.mdx'; +import GapFillingJava from './content/_gap-filling-java.mdx'; +import GapFillingNodejs from './content/_gap-filling-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/overview-and-syntax.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/overview-and-syntax.mdx index fa543b671f..fc9a3d9466 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/overview-and-syntax.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/overview-and-syntax.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewAndSyntaxCsharp from './_overview-and-syntax-csharp.mdx'; -import OverviewAndSyntaxPython from './_overview-and-syntax-python.mdx'; -import OverviewAndSyntaxPhp from './_overview-and-syntax-php.mdx'; -import OverviewAndSyntaxNodejs from './_overview-and-syntax-nodejs.mdx'; +import OverviewAndSyntaxCsharp from './content/_overview-and-syntax-csharp.mdx'; +import OverviewAndSyntaxPython from './content/_overview-and-syntax-python.mdx'; +import OverviewAndSyntaxPhp from './content/_overview-and-syntax-php.mdx'; +import OverviewAndSyntaxNodejs from './content/_overview-and-syntax-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/stream-timeseries.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/stream-timeseries.mdx index 5a6f10ac13..a7c2bea4d3 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/stream-timeseries.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/stream-timeseries.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamTimeseriesCsharp from './_stream-timeseries-csharp.mdx'; -import StreamTimeseriesJava from './_stream-timeseries-java.mdx'; +import StreamTimeseriesCsharp from './content/_stream-timeseries-csharp.mdx'; +import StreamTimeseriesJava from './content/_stream-timeseries-java.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/querying/using-indexes.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/querying/using-indexes.mdx index 1e1a9610a7..851d611baf 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/querying/using-indexes.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/querying/using-indexes.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingIndexesCsharp from './_using-indexes-csharp.mdx'; -import UsingIndexesPython from './_using-indexes-python.mdx'; -import UsingIndexesPhp from './_using-indexes-php.mdx'; -import UsingIndexesNodejs from './_using-indexes-nodejs.mdx'; +import UsingIndexesCsharp from './content/_using-indexes-csharp.mdx'; +import UsingIndexesPython from './content/_using-indexes-python.mdx'; +import UsingIndexesPhp from './content/_using-indexes-php.mdx'; +import UsingIndexesNodejs from './content/_using-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/rollup-and-retention.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/rollup-and-retention.mdx index 8a309352ba..e3b7ce575e 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/rollup-and-retention.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/rollup-and-retention.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RollupAndRetentionCsharp from './_rollup-and-retention-csharp.mdx'; -import RollupAndRetentionPython from './_rollup-and-retention-python.mdx'; -import RollupAndRetentionPhp from './_rollup-and-retention-php.mdx'; -import RollupAndRetentionNodejs from './_rollup-and-retention-nodejs.mdx'; +import RollupAndRetentionCsharp from './content/_rollup-and-retention-csharp.mdx'; +import RollupAndRetentionPython from './content/_rollup-and-retention-python.mdx'; +import RollupAndRetentionPhp from './content/_rollup-and-retention-php.mdx'; +import RollupAndRetentionNodejs from './content/_rollup-and-retention-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/document-extensions/timeseries/time-series-and-other-features.mdx b/versioned_docs/version-7.1/document-extensions/timeseries/time-series-and-other-features.mdx index 2653af2170..26342fe5f8 100644 --- a/versioned_docs/version-7.1/document-extensions/timeseries/time-series-and-other-features.mdx +++ b/versioned_docs/version-7.1/document-extensions/timeseries/time-series-and-other-features.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TimeSeriesAndOtherFeaturesCsharp from './_time-series-and-other-features-csharp.mdx'; -import TimeSeriesAndOtherFeaturesNodejs from './_time-series-and-other-features-nodejs.mdx'; +import TimeSeriesAndOtherFeaturesCsharp from './content/_time-series-and-other-features-csharp.mdx'; +import TimeSeriesAndOtherFeaturesNodejs from './content/_time-series-and-other-features-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/glossary/blittable-json-reader-object.mdx b/versioned_docs/version-7.1/glossary/blittable-json-reader-object.mdx index 70c4674e39..5fd306c8db 100644 --- a/versioned_docs/version-7.1/glossary/blittable-json-reader-object.mdx +++ b/versioned_docs/version-7.1/glossary/blittable-json-reader-object.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BlittableJsonReaderObjectCsharp from './_blittable-json-reader-object-csharp.mdx'; +import BlittableJsonReaderObjectCsharp from './content/_blittable-json-reader-object-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/_blittable-json-reader-object-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_blittable-json-reader-object-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_blittable-json-reader-object-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_blittable-json-reader-object-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_copy-attachment-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_copy-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_copy-attachment-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_copy-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_counters-batch-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_counters-batch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_counters-batch-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_counters-batch-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_delete-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_delete-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_delete-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_delete-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_index-query-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_index-query-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_index-query-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_index-query-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_move-attachment-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_move-attachment-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_move-attachment-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_move-attachment-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_patch-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_patch-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_patch-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_patch-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_put-command-data-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_put-command-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_put-command-data-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_put-command-data-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_query-result-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_query-result-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_query-result-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_query-result-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_stream-query-statistics-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_stream-query-statistics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_stream-query-statistics-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_stream-query-statistics-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/_stream-result-csharp.mdx b/versioned_docs/version-7.1/glossary/content/_stream-result-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/glossary/_stream-result-csharp.mdx rename to versioned_docs/version-7.1/glossary/content/_stream-result-csharp.mdx diff --git a/versioned_docs/version-7.1/glossary/copy-attachment-command-data.mdx b/versioned_docs/version-7.1/glossary/copy-attachment-command-data.mdx index 6a30c9dbb1..6675ff9b49 100644 --- a/versioned_docs/version-7.1/glossary/copy-attachment-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/copy-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CopyAttachmentCommandDataCsharp from './_copy-attachment-command-data-csharp.mdx'; +import CopyAttachmentCommandDataCsharp from './content/_copy-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/counters-batch-command-data.mdx b/versioned_docs/version-7.1/glossary/counters-batch-command-data.mdx index d5d5a0082b..7a0db6fcfb 100644 --- a/versioned_docs/version-7.1/glossary/counters-batch-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/counters-batch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CountersBatchCommandDataCsharp from './_counters-batch-command-data-csharp.mdx'; +import CountersBatchCommandDataCsharp from './content/_counters-batch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/delete-command-data.mdx b/versioned_docs/version-7.1/glossary/delete-command-data.mdx index 38435c45ee..749f878b71 100644 --- a/versioned_docs/version-7.1/glossary/delete-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/delete-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DeleteCommandDataCsharp from './_delete-command-data-csharp.mdx'; +import DeleteCommandDataCsharp from './content/_delete-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/index-query.mdx b/versioned_docs/version-7.1/glossary/index-query.mdx index 01cc1d5ed1..451241b64f 100644 --- a/versioned_docs/version-7.1/glossary/index-query.mdx +++ b/versioned_docs/version-7.1/glossary/index-query.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexQueryCsharp from './_index-query-csharp.mdx'; +import IndexQueryCsharp from './content/_index-query-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/move-attachment-command-data.mdx b/versioned_docs/version-7.1/glossary/move-attachment-command-data.mdx index 8db8900713..d2e2660fc3 100644 --- a/versioned_docs/version-7.1/glossary/move-attachment-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/move-attachment-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MoveAttachmentCommandDataCsharp from './_move-attachment-command-data-csharp.mdx'; +import MoveAttachmentCommandDataCsharp from './content/_move-attachment-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/patch-command-data.mdx b/versioned_docs/version-7.1/glossary/patch-command-data.mdx index 7bbe4e1cdc..1eede87ec5 100644 --- a/versioned_docs/version-7.1/glossary/patch-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/patch-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PatchCommandDataCsharp from './_patch-command-data-csharp.mdx'; +import PatchCommandDataCsharp from './content/_patch-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/put-command-data.mdx b/versioned_docs/version-7.1/glossary/put-command-data.mdx index 666f2389ac..0e25b46118 100644 --- a/versioned_docs/version-7.1/glossary/put-command-data.mdx +++ b/versioned_docs/version-7.1/glossary/put-command-data.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PutCommandDataCsharp from './_put-command-data-csharp.mdx'; +import PutCommandDataCsharp from './content/_put-command-data-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/query-result.mdx b/versioned_docs/version-7.1/glossary/query-result.mdx index 90c800fc56..30d733edc8 100644 --- a/versioned_docs/version-7.1/glossary/query-result.mdx +++ b/versioned_docs/version-7.1/glossary/query-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryResultCsharp from './_query-result-csharp.mdx'; +import QueryResultCsharp from './content/_query-result-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/stream-query-statistics.mdx b/versioned_docs/version-7.1/glossary/stream-query-statistics.mdx index 3a03b9bae5..e684cfce6c 100644 --- a/versioned_docs/version-7.1/glossary/stream-query-statistics.mdx +++ b/versioned_docs/version-7.1/glossary/stream-query-statistics.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamQueryStatisticsCsharp from './_stream-query-statistics-csharp.mdx'; +import StreamQueryStatisticsCsharp from './content/_stream-query-statistics-csharp.mdx'; diff --git a/versioned_docs/version-7.1/glossary/stream-result.mdx b/versioned_docs/version-7.1/glossary/stream-result.mdx index 2814d0ebb9..ca5bcaee4a 100644 --- a/versioned_docs/version-7.1/glossary/stream-result.mdx +++ b/versioned_docs/version-7.1/glossary/stream-result.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StreamResultCsharp from './_stream-result-csharp.mdx'; +import StreamResultCsharp from './content/_stream-result-csharp.mdx'; diff --git a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-csharp.mdx deleted file mode 100644 index 490d55a13e..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-csharp.mdx +++ /dev/null @@ -1,247 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`public class BlogPost -\{ - public string Author \{ get; set; \} - public string Title \{ get; set; \} - public string Text \{ get; set; \} - - // Blog post readers can leave comments - public List Comments \{ get; set; \} -\} - -public class BlogPostComment -\{ - public string Author \{ get; set; \} - public string Text \{ get; set; \} - - // Allow nested comments, enabling replies to existing comments - public List Comments \{ get; set; \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`public class BlogPosts_ByCommentAuthor : - AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor() - { - Map = blogposts => - from blogpost in blogposts - let authors = Recurse(blogpost, x => x.Comments) - select new IndexEntry - { - Authors = authors.Select(x => x.Author) - }; - } -} -`} - - - - -{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string[] Authors { get; set; } - } - - public BlogPosts_ByCommentAuthor_JS() - { - Maps = new HashSet - { - @"map('BlogPosts', function (blogpost) { - - var authors = - recurse(blogpost.Comments, function(x) { - return x.Comments; - }) - .filter(function(comment) { - return comment.Author != null; - }) - .map(function(comment) { - return comment.Author; - }); - - return { - Authors: authors - }; - });" - }; - } -} -`} - - - - -{`store.Maintenance.Send(new PutIndexesOperation( - new IndexDefinition - { - Name = "BlogPosts/ByCommentAuthor", - Maps = - { - @"from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.Comments)) - let authorNames = authors.Select(x => x.Author) - select new - { - Authors = authorNames - }" - } - })); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`List results = session - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToList(); -`} - - - - -{`List results = await asyncSession - .Query() - // Query for all blog posts that contain comments by 'Moon': - .Where(x => x.Authors.Any(a => a == "Moon")) - .OfType() - .ToListAsync(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - // Query for all blog posts that contain comments by 'Moon': - .WhereEquals("Authors", "Moon") - .ToList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-nodejs.mdx deleted file mode 100644 index 45f87fdf89..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-nodejs.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost \{ - constructor(title, author, text, comments) \{ - this.title = title; - this.author = author; - this.text = text; - - // Blog post readers can leave comments - this.comments = comments; - \} -\} - -class BlogPostComment \{ - constructor(author, text, comments) \{ - this.author = author; - this.text = text; - - // Allow nested comments, enabling replies to existing comments - this.comments = comments; - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "author": "John", - "title": "Post title..", - "text": "Post text..", - "comments": [ - \{ - "author": "Moon", - "text": "Comment text..", - "comments": [ - \{ - "author": "Bob", - "text": "Comment text.." - \}, - \{ - "author": "Adel", - "text": "Comment text..", - "comments": \{ - "author": "Moon", - "text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - this.map = \` - docs.BlogPosts.Select(post => new { - authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) - })\`; - } -} -`} - - - - -{`const indexDefinition = new IndexDefinition(); - -indexDefinition.name = "BlogPosts/ByCommentAuthor"; -indexDefinition.maps = new Set([ - \`from blogpost in docs.BlogPosts - let authors = Recurse(blogpost, (Func)(x => x.comments)) - let authorNames = authors.Select(x => x.author) - select new - { - Authors = authorNames - }\` -]); - -await store.maintenance.send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`const results = await session - .query({ indexName: "BlogPosts/ByCommentAuthor" }) - // Query for all blog posts that contain comments by 'Moon': - .whereEquals("authors", "Moon") - .all(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-php.mdx deleted file mode 100644 index aab5ed3dfa..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-php.mdx +++ /dev/null @@ -1,280 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost -\{ - private ?string $author = null; - private ?string $title = null; - private ?string $text = null; - - // Blog post readers can leave comments - public ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getTitle(): ?string - \{ - return $this->title; - \} - - public function setTitle(?string $title): void - \{ - $this->title = $title; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostComment -\{ - private ?string $author = null; - private ?string $text = null; - - // Comments can be left recursively - private ?BlogPostCommentList $comments = null; - - public function getAuthor(): ?string - \{ - return $this->author; - \} - - public function setAuthor(?string $author): void - \{ - $this->author = $author; - \} - - public function getText(): ?string - \{ - return $this->text; - \} - - public function setText(?string $text): void - \{ - $this->text = $text; - \} - - public function getComments(): ?BlogPostCommentList - \{ - return $this->comments; - \} - - public function setComments(?BlogPostCommentList $comments): void - \{ - $this->comments = $comments; - \} -\} - -class BlogPostCommentList extends TypedList -\{ - public function __construct() - \{ - parent::__construct(BlogPost::class); - \} -\} -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor_Result -{ - private ?StringArray $authors = null; - - public function getAuthors(): ?StringArray - { - return $this->authors; - } - - public function setAuthors(?StringArray $authors): void - { - $this->authors = $authors; - } -} - -class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; - } -} -`} - - - - -{`$indexDefinition = new IndexDefinition(); -$indexDefinition->setName("BlogPosts/ByCommentAuthor"); -$indexDefinition->setMaps([ - "from blogpost in docs.BlogPosts - from comment in Recurse(blogpost, (Func)(x => x.Comments)) - select new - { - Author = comment.Author - }" -]); - -$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`/** @var array $results */ -$results = $session - ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "john") - ->ofType(BlogPost::class) - ->toList(); -`} - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) - ->whereEquals("authors", "John") - ->toList(); -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-python.mdx deleted file mode 100644 index 4c5594a1fb..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-python.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. - -* In this Page: - * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) - * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) - * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) - - -## Hierarchical data - -One significant advantage of document databases is their tendency not to impose limits on data structuring. -**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: - - - -{`class BlogPost: - def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.title = title - self.text = text - - # Blog post readers can leave comments - self.comments = comments - - -class BlogPostComment: - def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): - self.author = author - self.text = text - - # Allow nested comments, enabling replies to existing comments - self.comments = comments -`} - - - -Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, -and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. - -For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. - -`BlogPosts/1-A`: - - - -{`\{ - "Author": "John", - "Title": "Post title..", - "Text": "Post text..", - "Comments": [ - \{ - "Author": "Moon", - "Text": "Comment text..", - "Comments": [ - \{ - "Author": "Bob", - "Text": "Comment text.." - \}, - \{ - "Author": "Adel", - "Text": "Comment text..", - "Comments": \{ - "Author": "Moon", - "Text": "Comment text.." - \} - \} - ] - \} - ], - "@metadata": \{ - "@collection": "BlogPosts" - \} -\} -`} - - - - - -## Index hierarchical data - -To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. - -The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. -We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. - - - - -{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): - class Result: - def __init__(self, authors: List[str] = None): - self.authors = authors - - def __init__(self): - super().__init__() - self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" -`} - - - - -{`store.maintenance.send( - PutIndexesOperation( - IndexDefinition( - name="BlogPosts/ByCommentAuthor", - maps={ - """from blogpost in docs.BlogPosts - in Recurse(blogpost, (Func)(x => x.comments)) -select new -{ - comment.author -}""" - }, - ) - ) -) -`} - - - - - - -## Query the index - -The index can be queried for all blog posts that contain comments made by specific authors. - -**Query the index using code**: - - - - -{`results = list( - session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( - "authors", "Moon" - ) -) -`} - - - - -{`from index "BlogPosts/ByCommentAuthor" -where Authors == "Moon" -`} - - - - -**Query the index using Studio**: - - * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: - - !["List of Indexes view"](./assets/list-of-indexes-view.png) - - * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: - - !["Query View"](./assets/query-view.png) - - * View the list of terms indexed by the `Recurse` method: - - !["Click to View Index Terms"](./assets/click-to-view-terms.png) - - !["Index Terms"](./assets/index-terms.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-nested-data-csharp.mdx b/versioned_docs/version-7.1/indexes/_indexing-nested-data-csharp.mdx deleted file mode 100644 index 64f96838de..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-nested-data-csharp.mdx +++ /dev/null @@ -1,579 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`public class OnlineShop -{ - public string ShopName { get; set; } - public string Email { get; set; } - public List TShirts { get; set; } // Nested data -} - -public class TShirt -{ - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - public decimal Price { get; set; } - public int Sold { get; set; } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var onlineShops = new[] -{ - // Shop1 - new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, - new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, - new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} - }}, - // Shop2 - new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { - new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, - new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } - }}, - // Shop3 - new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { - new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, - new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, - new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, - new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } - }} -}; - -using (var session = store.OpenSession()) -{ - foreach (var shop in onlineShops) - { - session.Store(shop); - } - - session.SaveChanges(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields: - public IEnumerable Colors \{ get; set; \} - public IEnumerable Sizes \{ get; set; \} - public IEnumerable Logos \{ get; set; \} - \} - - public Shops_ByTShirt_Simple() - \{ - Map = shops => from shop in shops - // Creating a SINGLE index-entry per document: - select new IndexEntry - \{ - // Each index-field will hold a collection of nested values from the document - Colors = shop.TShirts.Select(x => x.Color), - Sizes = shop.TShirts.Select(x => x.Size), - Logos = shop.TShirts.Select(x => x.Logo) - \}; - \} -\} -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToList(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = await asyncSession - .Query() - // Filter query results by a nested value - .Where(x => x.Colors.Contains("red")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Query for all shop documents that have a red TShirt -var shopsThatHaveRedShirts = session.Advanced - .DocumentQuery() - // Filter query results by a nested value - .ContainsAny(x => x.Colors, new[] { "Red" }) - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -var GreenAndLarge = session - .Query() - .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) - .OfType() - .ToList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public string Size { get; set; } - public string Logo { get; set; } - } - - public Shops_ByTShirt_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - Size = shirt.Size, - Logo = shirt.Logo - }; - } -} -`} - - - - -{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask -{ - public Shops_ByTShirt_JS() - { - Maps = new HashSet - { - @"map('OnlineShops', function (shop){ - var res = []; - shop.TShirts.forEach(shirt => { - res.push({ - Color: shirt.Color, - Size: shirt.Size, - Logo: shirt.Logo - }) - }); - return res; - })" - }; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToList(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = await asyncSession - .Query() - // Query for documents that have a "Medium Red TShirt" - .Where(x => x.Color == "red" && x.Size == "M") - .OfType() - .ToListAsync(); -`} - - - - -{`// Query the fanout index: -// ======================= -var shopsThatHaveMediumRedShirts = session.Advanced - .DocumentQuery() - // Query for documents that have a "Medium Red TShirt" - .WhereEquals(x => x.Color, "red") - .AndAlso() - .WhereEquals(x=> x.Size, "M") - .OfType() - .ToList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -public class Sales_ByTShirtColor_Fanout : - AbstractIndexCreationTask -{ - public class IndexEntry - { - // The index-fields: - public string Color { get; set; } - public int ItemsSold { get; set; } - public decimal TotalSales { get; set; } - } - - public Sales_ByTShirtColor_Fanout() - { - Map = shops => - from shop in shops - from shirt in shop.TShirts - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - select new IndexEntry - { - Color = shirt.Color, - ItemsSold = shirt.Sold, - TotalSales = shirt.Price * shirt.Sold - }; - - Reduce = results => from result in results - group result by result.Color - into g - select new - { - // Calculate sales per color - Color = g.Key, - ItemsSold = g.Sum(x => x.ItemsSold), - TotalSales = g.Sum(x => x.TotalSales) - }; - } -} -`} - - - - -{`public class Product_Sales : AbstractJavaScriptIndexCreationTask -{ - public class Result - { - public string Product { get; set; } - - public int Count { get; set; } - - public decimal Total { get; set; } - } - - public Product_Sales() - { - Maps = new HashSet() - { - @"map('orders', function(order){ - var res = []; - order.Lines.forEach(l => { - res.push({ - Product: l.Product, - Count: 1, - Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) - }) - }); - return res; - })" - }; - - Reduce = @"groupBy(x => x.Product) - .aggregate(g => { - return { - Product : g.key, - Count: g.values.reduce((sum, x) => x.Count + sum, 0), - Total: g.values.reduce((sum, x) => x.Total + sum, 0) - } - })"; - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = await asyncSession - .Query() - // Query for index-entries that contain "black" - .Where(x => x.Color == "black") - .FirstOrDefaultAsync(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`// Query the fanout index: -// ======================= -var queryResult = session.Advanced - .DocumentQuery() - // Query for index-entries that contain "black" - .WhereEquals(x => x.Color, "black") - .FirstOrDefault(); - -// Get total sales for black TShirts -var blackShirtsSales = queryResult?.TotalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490.0 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-nested-data-java.mdx b/versioned_docs/version-7.1/indexes/_indexing-nested-data-java.mdx deleted file mode 100644 index c1acf413a1..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-nested-data-java.mdx +++ /dev/null @@ -1,131 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: - - - - -{`public static class Orders_ByProduct extends AbstractIndexCreationTask { - public Orders_ByProduct() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + - " Product = orderLine.Product, " + - " ProductName = orderLine.ProductName " + - "})"; - } -} -`} - - - - -{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { - public Orders_ByProduct() { - setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " ProductName: l.ProductName\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - "})")); - } -} -`} - - - - -A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. - -The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: - - - - -{`public static class Product_Sales extends AbstractIndexCreationTask { - public Product_Sales() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + - " Product = line.Product, " + - " Count = 1, " + - " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + - "})"; - - reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + - " Product = g.Key,\\n" + - " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + - " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + - "})"; - } -} -`} - - - - -{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { - public Product_Sales() { - setMaps(Sets.newHashSet("map('orders', function(order){\\n" + - " var res = [];\\n" + - " order.Lines.forEach(l => {\\n" + - " res.push({\\n" + - " Product: l.Product,\\n" + - " Count: 1,\\n" + - " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + - " })\\n" + - " });\\n" + - " return res;\\n" + - " })")); - - setReduce("groupBy(x => x.Product)\\n" + - " .aggregate(g => {\\n" + - " return {\\n" + - " Product : g.key,\\n" + - " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + - " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + - " }\\n" + - " })"); - } -} -`} - - - - -The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. -RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. - - -Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: - -- `Raven/MaxSimpleIndexOutputsPerDocument` -- `Raven/MaxMapReduceIndexOutputsPerDocument` - -are no longer valid. - -RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. - - - -## Performance Hints - -Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: - -![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - -The details will give you the following info: - -![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). - -## Paging - -Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results -is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/_indexing-nested-data-nodejs.mdx deleted file mode 100644 index e9694f16a7..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-nested-data-nodejs.mdx +++ /dev/null @@ -1,399 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop { - constructor( - shopName = '', - email = '', - tShirts = {} // Will contain the nested data - ) { - Object.assign(this, { shopName, email, tShirts }); - } -} - -class TShirt { - constructor( - color = '', - size = '', - logo = '', - price = 0, - sold = 0 - ) { - Object.assign(this, { color, size, logo, price, sold }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -const bulkInsert = store.bulkInsert(); - -const onlineShops = [ - new OnlineShop("Shop1", "sales@shop1.com", [ - new TShirt("Red", "S", "Bytes and Beyond", 25, 2), - new TShirt("Red", "M", "Bytes and Beyond", 25, 4), - new TShirt("Blue", "M", "Query Everything", 28, 5), - new TShirt("Green", "L", "Data Driver", 30, 3) - ]), - new OnlineShop("Shop2", "sales@shop2.com", [ - new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), - new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), - new TShirt("Green", "M", "Big Data Dreamer", 25, 9), - new TShirt("Black", "L", "Data Mining Expert", 20, 11) - ]), - new OnlineShop("Shop3", "sales@shop3.com", [ - new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), - new TShirt("Blue", "M", "Data Geek", 20, 6), - new TShirt("Black", "L", "Data Revolution", 15, 8), - new TShirt("Black", "XL", "Data Revolution", 15, 10) - ]) -]; - -for (const shop of onlineShops ) { - await bulkInsert.store(shop); -} - -await bulkInsert.finish(); -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating a SINGLE index-entry per document: - this.map("OnlineShops", shop => \{ - return \{ - // Each index-field will hold a collection of nested values from the document - colors: shop.tShirts.map(x => x.color), - sizes: shop.tShirts.map(x => x.size), - logos: shop.tShirts.map(x => x.logo) - \}; - \}); - \} -\} -`} - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -const results = await session - .query({ indexName: "Shops/ByTShirt/Simple" }) - // Filter query results by a nested value - .containsAny("colors", ["red"]) - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `AND` condition. - For example: - - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -const greenAndLarge = await session - .query(\{ indexName: "Shops/ByTShirt/Simple" \}) - .containsAny("colors", ["green"]) - .andAlso() - .containsAny("sizes", ["L"]) - .all(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the tShirts list - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - \}; - \}); - \}); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const shopsThatHaveMediumRedShirts = await session - .query({ indexName: "Shops/ByTShirt/Fanout" }) - // Query for documents that have a "Medium Red TShirt" - .whereEquals("color", "red") - .andAlso() - .whereEquals("size", "M") - .all(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where color == "red" and size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the tShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ - constructor () \{ - super(); - - this.map("OnlineShops", shop => \{ - return shop.tShirts.map(shirt => \{ - return \{ - // Define the index-fields: - color: shirt.color, - itemsSold: shirt.sold, - totalSales: shirt.price * shirt.sold - \}; - \}); - \}); - - this.reduce(results => results - .groupBy(shirt => shirt.color) - .aggregate(g => \{ - return \{ - // Calculate sales per color - color: g.key, - itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), - totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), - \} - \})); - \} -\} -`} - - - - - - -{`// Query the fanout index: -// ======================= -const queryResult = await session - .query({ indexName: "Sales/ByTShirtColor/Fanout" }) - // Query for index-entries that contain "black" - .whereEquals("color", "black") - .firstOrNull(); - -// Get total sales for black TShirts -const blackShirtsSales = queryResult?.totalSales ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where color == "black" -`} - - - - - - -{`// Query results: -// ============== - -// With the sample data used in this article, -// The total sales revenue from black TShirts sold (in all shops) is 490 -`} - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `totalResults` property (available when calling the query `statistics()` method) - will contain the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-nested-data-php.mdx b/versioned_docs/version-7.1/indexes/_indexing-nested-data-php.mdx deleted file mode 100644 index 6b4165db63..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-nested-data-php.mdx +++ /dev/null @@ -1,624 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop -{ - private ?string $shopName = null; - private ?string $email = null; - public ?TShirtArray $tShirts = null; // Nested data - - public function __construct( - ?string $shopName = null, - ?string $email = null, - ?TShirtArray $tShirts = null - ) { - $this->shopName = $shopName; - $this->email = $email; - $this->tShirts = $tShirts; - } - - public function getShopName(): ?string - { - return $this->shopName; - } - - public function setShopName(?string $shopName): void - { - $this->shopName = $shopName; - } - - public function getEmail(): ?string - { - return $this->email; - } - - public function setEmail(?string $email): void - { - $this->email = $email; - } - - public function getTShirts(): ?TShirtArray - { - return $this->tShirts; - } - - public function setTShirts(?TShirtArray $tShirts): void - { - $this->tShirts = $tShirts; - } -} - -class TShirt -{ - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - private ?float $price = null; - private ?int $sold = null; - - public function __construct( - ?string $color = null, - ?string $size = null, - ?string $logo = null, - ?float $price = null, - ?int $sold = null - ) { - $this->color = $color; - $this->size = $size; - $this->logo = $logo; - $this->price = $price; - $this->sold = $sold; - } - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getSold(): ?int - { - return $this->sold; - } - - public function setSold(?int $sold): void - { - $this->sold = $sold; - } -} - -class TShirtArray extends TypedArray -{ - public function __construct() - { - parent::__construct(TShirt::class); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$onlineShops = []; - -// Shop1 -$onlineShops[] = new OnlineShop( - shopName: "Shop1", - email: "sales@shop1.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), - new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), - new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), - new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) - ]) -); - -// Shop2 -$onlineShops[] = new OnlineShop( - shopName: "Shop2", - email: "sales@shop2.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), - new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), - new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), - new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) - ]) -); - -// Shop3 -$onlineShops[] = new OnlineShop( - shopName: "Shop3", - email: "sales@shop3.com", - tShirts: TShirtArray::fromArray([ - new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), - new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), - new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), - new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) - ]) -); - -$session = $store->openSession(); -try { - /** @var OnlineShop $shop */ - foreach ($onlineShops as $shop) { - $session->store($shop); - } - - $session->SaveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`_query_1 - // Query for all shop documents that have a red TShirt - $shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`// Query for all shop documents that have a red TShirt -$shopsThatHaveRedShirts = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - // Filter query results by a nested value - ->containsAny("colors", [ "red" ]) - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`// Results will include the following shop documents: -// ================================================== -// * Shop1 -// * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`// You want to query for shops containing "Large Green TShirts", -// aiming to get only "Shop1" as a result since it has such a combination, -// so you attempt this query: -$greenAndLarge = $session - ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) - ->whereEquals("color", "green") - ->andAlso() - ->whereEquals("size", "L") - ->ofType(OnlineShop::class) - ->toList(); - -// But, the results of this query will include BOTH "Shop1" & "Shop2" -// since the index-entries do not keep the original sub-objects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`// A fanout map-index: -// =================== -class Shops_ByTShirt_Fanout_IndexEntry -{ - // The index-fields: - private ?string $color = null; - private ?string $size = null; - private ?string $logo = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getSize(): ?string - { - return $this->size; - } - - public function setSize(?string $size): void - { - $this->size = $size; - } - - public function getLogo(): ?string - { - return $this->logo; - } - - public function setLogo(?string $logo): void - { - $this->logo = $logo; - } -} - -class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color," . - " size = shirt.size," . - " logo = shirt.logo" . - "}"; - } -} -`} - - - - -{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - " - ]); - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -$shopsThatHaveMediumRedShirts = $session - ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) - // Query for documents that have a "Medium Red TShirt" - ->whereEquals("color", "red") - ->andAlso() - ->whereEquals("size", "M") - ->ofType(OnlineShop::class) - ->toList(); -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`// Query results: -// ============== - -// Only the 'Shop1' document will be returned, -// since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`// A fanout map-reduce index: -// ========================== -class Sales_ByTShirtColor_Fanout_IndexEntry { - // The index-fields: - private ?string $color = null; - private ?int $itemsSold = null; - private ?float $totalSales = null; - - public function getColor(): ?string - { - return $this->color; - } - - public function setColor(?string $color): void - { - $this->color = $color; - } - - public function getItemsSold(): ?int - { - return $this->itemsSold; - } - - public function setItemsSold(?int $itemsSold): void - { - $this->itemsSold = $itemsSold; - } - - public function getTotalSales(): ?float - { - return $this->totalSales; - } - - public function setTotalSales(?float $totalSales): void - { - $this->totalSales = $totalSales; - } -} -class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask -{ - - public function __construct() - { - parent::__construct(); - - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - $this->map = - "from shop in docs.OnlineShops " . - "from shirt in shop.t_shirts " . - // Creating MULTIPLE index-entries per document, - // an index-entry for each sub-object in the TShirts list - "select new {" . - " color = shirt.color, " . - " items_sold = shirt.sold, " . - " total_sales = shirt.price * shirt.sold" . - "}"; - - $this->reduce = - "from result in results " . - "group result by result.color " . - "into g select new {" . - " color = g.Key," . - // Calculate sales per color - " items_sold = g.Sum(x => x.items_sold)," . - " total_sales = g.Sum(x => x.total_sales)" . - "}"; - - } -} -`} - - - - - - - -{`// Query the fanout index: -// ======================= -/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ -$queryResult = $session - ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) - // Query for index-entries that contain "black" - ->whereEquals("color", "black") - ->firstOrDefault(); - -// Get total sales for black TShirts -$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-nested-data-python.mdx b/versioned_docs/version-7.1/indexes/_indexing-nested-data-python.mdx deleted file mode 100644 index 130d9519bd..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-nested-data-python.mdx +++ /dev/null @@ -1,444 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* JSON documents can have nested structures, where one document contains other objects or arrays of objects. - -* Use a static-index to facilitate querying for documents based on the nested data. - -* In this page: - - * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) - - * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) - * [The index](../indexes/indexing-nested-data.mdx#theIndex) - * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) - * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) - * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) - - * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) - * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) - * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) - * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) - * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) - * [Paging](../indexes/indexing-nested-data.mdx#paging) - - -## Sample data - -* The examples in this article are based on the following **Classes** and **Sample Data**: - - - - -{`class OnlineShop: - def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): - self.shop_name = shop_name - self.email = email - self.t_shirts = t_shirts - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: - return cls( - json_data["shop_name"], - json_data["email"], - [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], - ) - - def to_json(self) -> Dict[str, Any]: - return { - "shop_name": self.shop_name, - "email": self.email, - "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], - } - - -class TShirt: - def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): - self.color = color - self.size = size - self.logo = logo - self.price = price - self.sold = sold - - @classmethod - def from_json(cls, json_data: Dict[str, Any]) -> TShirt: - return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) - - def to_json(self) -> Dict[str, Any]: - return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== -shop1_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), - TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), - TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), - TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), -] - -shop2_tshirts = [ - TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), - TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), - TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), - TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), -] - -shop3_tshirts = [ - TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), - TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), - TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), - TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), -] - -online_shops = [ - OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), - OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), - OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), -] - -Shops_ByTShirt_Simple().execute(store) -Shops_ByTShirt_Fanout().execute(store) -Sales_ByTShirtColor_Fanout().execute(store) - -with store.open_session() as session: - for shop in online_shops: - session.store(shop) - - session.save_changes() -`} - - - - - - -## Simple index - Single index-entry per document - -* **The index**: - - -{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): - # The index-fields: - self.colors = colors - self.sizes = sizes - self.logos = logos - - def __init__(self): - super().__init__() - # Creating a SINGLE index-entry per document: - self.map = ( - "from shop in docs.OnlineShops " - "select new \{ " - # Each index-field will hold a collection of nested values from the document - " colors = shop.t_shirts.Select(x => x.color)," - " sizes = shop.t_shirts.Select(x => x.size)," - " logos = shop.t_shirts.Select(x => x.logo)" - "\}" - ) -`} - - - -* **The index-entries**: - - ![Simple - index-entries](./assets/indexing-nested-data-1.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - The index has a single index-entry per document (3 entries in this example). - - 4. The index-field contains a collection of ALL nested values from the document. - e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: - `{"black", "blue", "red"}` - -* **Querying the index**: - - - - -{`# Query for all shop documents that have a red TShirt -shops_that_have_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["Red"]) - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Simple" -where Colors == "red" -`} - - - - - - -{`# Results will include the following shop documents: -# ================================================== -# * Shop1 -# * Shop3 -`} - - - -* **When to use**: - - * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. - - * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain - specific sub-objects which satisfy some `and_also` condition. - For example: - - -{`# You want to query for shops containing "Large Green TShirts", -# aiming to get only "Shop1" as a result since it has such a combination, -# so you attempt this query: -green_and_large = list( - session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) - .contains_any("colors", ["green"]) - .and_also() - .contains_any("sizes", "L") - .of_type(OnlineShop) -) - -# But, the results of this query will include BOTH "Shop1" & "Shop2" -# since the index-queries do not keep the original sub-subjects structure. -`} - - - - * To address this, you must use a **Fanout index** - as described below. - - - -## Fanout index - Multiple index-entries per document - -* **What is a Fanout index**: - - * A fanout index is an index that outputs multiple index-entries per document. - A separate index-entry is created for each nested sub-object from the document. - - * The fanout index is useful when you need to retrieve documents matching query criteria - that search for specific sub-objects that comply with some logical conditions. - -* **Fanout index - Map index example**: - - - - -{`# A fanout map-index: -# =================== -class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, size: str = None, logo: str = None): - self.color = color - self.size = size - self.logo = logo - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color," - " size = shirt.size," - " logo = shirt.logo" - "}" - ) -`} - - - - -{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('OnlineShops', function (shop){ - var res = []; - shop.t_shirts.forEach(shirt => { - res.push({ - color: shirt.color, - size: shirt.size, - logo: shirt.logo - }) - }); - return res; - }) - """ - } -`} - - - - - - - -{`# Query the fanout index: -# ======================= -shops_that_have_medium_red_shirts = list( - session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) - # Query for documents that have a "Medium Red TShirt" - .where_equals("color", "red") - .and_also() - .where_equals("size", "M") - .of_type(OnlineShop) -) -`} - - - - -{`from index "Shops/ByTShirt/Fanout" -where Color == "red" and Size == "M" -`} - - - - - - -{`# Query results: -# ============== -# -# Only the 'Shop1' document will be returned, -# since it is the only document that has the requested combination within the TShirt list. -`} - - - -* **The index-entries**: - ![Fanout - index-entries](./assets/indexing-nested-data-2.png) - - 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). - - 2. Check option: _Show raw index-entries instead of Matching documents_. - - 3. Each row represents an **index-entry**. - Each index-entry corresponds to an inner item in the TShirt list. - - 4. In this example, the total number of index-entries is **12**, - which is the total number of inner items in the TShirt list in all **3** documents in the collection. - -* **Fanout index - Map-Reduce index example**: - - * The fanout index concept applies to map-reduce indexes as well: - - - - -{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): - self.color = color - self.items_sold = items_sold - self.total_sales = total_sales - - def __init__(self): - super().__init__() - # Creating MULTIPLE index-entries per document, - # an index-entry for each sub-object in the TShirts list - self.map = ( - "from shop in docs.OnlineShops from shirt in shop.t_shirts " - "select new {" - " color = shirt.color, " - " items_sold = shirt.sold, " - " total_sales = shirt.price * shirt.sold" - "}" - ) - self.reduce = ( - "from result in results group result by result.color into g select new {" - " color = g.Key," - " items_sold = g.Sum(x => x.items_sold)," - " total_sales = g.Sum(x => x.total_sales)" - "}" - ) -`} - - - - - - - -{`# Query the fanout index: -# ======================= -query_result = ( - session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) - # Query for index-entries that contain "black" - .where_equals("color", "black").first() -) - -# Get total sales for black TShirts -black_shirts_sales = query_result.total_sales or 0 -`} - - - - -{`from index "Sales/ByTShirtColor/Fanout" -where Color == "black" -`} - - - - -* **Fanout index - Performance hints**: - - * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. - This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. - - * When the number of index-entries generated from a single document exceeds a configurable limit, - RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. - - * You can control when this performance hint is created by setting the - [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key - (default is 1024). - - * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items - will trigger the following alert: - - ![Figure 1. High indexing fanout ratio notification](./assets/fanout-index-performance-hint-1.png) - - * Clicking the 'Details' button will show the following info: - - ![Figure 2. Fanout index, performance hint details](./assets/fanout-index-performance-hint-2.png) - -* **Fanout index - Paging**: - - * A fanout index has more index-entries than the number of documents in the collection indexed. - Multiple index-entries "point" to the same document from which they originated, - as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. - - * When making a fanout index query that should return full documents (without projecting results), - the `TotalResults` property (available via the `QueryStatistics` object) will contain - the total number of index-entries and Not the total number of resulting documents. - - * **To overcome this when paging results**, you must take into account the number of "duplicate" - index-entries that are skipped internally by the server when serving the resulting documents. - - * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-csharp.mdx deleted file mode 100644 index d38ff436f4..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-csharp.mdx +++ /dev/null @@ -1,167 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`public class Animals_ByName : AbstractMultiMapIndexCreationTask -{ - public Animals_ByName() - { - AddMap(cats => from c in cats select new { c.Name }); - - AddMap(dogs => from d in dogs select new { d.Name }); - } -} -`} - - - - -{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask -{ - public Animals_ByName() - { - Maps = new HashSet() - { - @"map('cats', function (c){ return {Name: c.Name}})", - @"map('dogs', function (d){ return {Name: d.Name}})" - }; - } -} -`} - - - - -And query it like this: - - - - -{`IList results = session - .Query() - .Where(x => x.Name == "Mitzy") - .ToList(); -`} - - - - -{`List results = session - .Advanced - .DocumentQuery() - .WhereEquals("Name", "Mitzy") - .ToList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`DocumentStore store = new DocumentStore() -\{ - Conventions = - \{ - FindCollectionName = type => - \{ - if (typeof(Animal).IsAssignableFrom(type)) - return "Animals"; - return DocumentConventions.DefaultGetCollectionName(type); - \} - \} -\}; -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-java.mdx deleted file mode 100644 index 981e1ebc2a..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-java.mdx +++ /dev/null @@ -1,148 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`IndexDefinition indexDefinition = new IndexDefinition(); -indexDefinition.setName("Animals/ByName"); -HashSet maps = new HashSet<>(); -maps.add("docs.Cats.Select(c => new { name = c.name})"); -maps.add("docs.Dogs.Select(c => new { name = c.name})"); -indexDefinition.setMaps(maps); -`} - - - - -{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - public Animals_ByName() { - setMaps(Sets.newHashSet( - "map('cats', function (c){ return {name: c.name}})", - "map('dogs', function (d){ return {name: d.name}})" - )); - } -} -`} - - - - -And query it like this: - - - - -{`List results = session - .query(Animal.class, Query.index("Animals/ByName")) - .whereEquals("name", "Mitzy") - .toList(); -`} - - - - -{`from index 'Animals/ByName' -where name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`try (IDocumentStore store = new DocumentStore()) \{ - store.getConventions().setFindCollectionName(clazz -> \{ - if (Animal.class.isAssignableFrom(clazz)) \{ - return "Animals"; - \} - - return DocumentConventions.defaultGetCollectionName(clazz); - \}); -\} -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-nodejs.mdx deleted file mode 100644 index 6bd96b37be..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-nodejs.mdx +++ /dev/null @@ -1,297 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this page: - * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) - * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) - * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) - * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) - * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) - - -## The challenge - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -
-**By default**: -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - - -{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Cat extends Animal { } -`} - - - - -And for Dogs: - - - - -{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index the 'name' field from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -{`class Animal { - constructor(name) { - this.name = name; - } -} - -class Dog extends Animal { } -`} - - - - -**The challenge**: -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - - -## Possible solutions - - - - **Multi-Map Index**: -Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. - - - - -{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { - constructor() { - super(); - - // Index documents from the CATS collection - this.map('Cats', cat => { - return { - name: cat.name - }; - }); - - // Index documents from the DOGS collection - this.map('Dogs', dog => { - return { - name: dog.name - }; - }); - } -} -`} - - - - -Query the Multi-map index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Polymorphic index**: -Another option is to create a polymorphic-index. - -Use method `WhereEntityIs` within your index definition to index documents from all collections -listed in the method. - - - - -{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Index documents from both the CATS collection and the DOGS collection - this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") - select new { - animal.name - }\`; - } -} -`} - - - - -Query the polymorphic-index: - - - - -{`const catsAndDogs = await session - // Query the index - .query({ indexName: "CatsAndDogs/ByName" }) - // Look for all Cats or Dogs that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the CATS and DOGS collection -`} - - - - -{`from index "CatsAndDogs/ByName" -where name == "Mitzy" -`} - - - - - - - - **Customize collection**: -This option involves customizing the collection name that is assigned to documents created from -subclasses of the _Animal_ class. - -This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. - - - -{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); - -// Customize the findCollectionName convention -documentStore.conventions.findCollectionName = (type) => \{ - const typeName = type.name; - - // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection - if (typeName === "Cat" || typeName === "Dog") \{ - return "Animals"; - \} - - // All other documents will be assgined the default collection name - return DocumentConventions.defaultGetCollectionName(type); -\} -`} - - - -With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. - -Now you can define a Map-index on the "Animals" collection: - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - // Index documents from the ANIMALS collection - this.map('Animals', animal => { - return { - name: animal.name - }; - }); - } -} -`} - - - - -Query the index: - - - - -{`const animals = await session - // Query the index - .query({ indexName: "Animals/ByName" }) - // Look for all Animals that are named 'Mitzy' :)) - .whereEquals("name", "Mitzy") - .all(); - -// Results will include matching documents from the ANIMALS collection -`} - - - - -{`from index "Animals/ByName" -where name == "Mitzy" -`} - - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-php.mdx deleted file mode 100644 index 319f416978..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-php.mdx +++ /dev/null @@ -1,158 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName extends AbstractMultiMapIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->addMap("from c in docs.Cats select new { c.name }"); - $this->addMap("from d in docs.Dogs select new { d.name }"); - } -} -`} - - - - -{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})" - ]); - } -} -`} - - - - -And query it like this: - - - - -{`/** @var array $results */ -$results = $session - ->advanced() - ->documentQuery(Animal::class, Animals_ByName::class) - ->whereEquals("Name", "Mitzy") - ->toList(); -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`$store = new DocumentStore(); -$store->getConventions()->setFindCollectionName( - function (?string $className): string \{ - if (is_a($className, Animal::class)) \{ - return "Animals"; - \} - return DocumentConventions::defaultGetCollectionName($className); - \} -); -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-python.mdx deleted file mode 100644 index d55f33b8d3..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-polymorphic-data-python.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, - and do not consider the inheritance hierarchy. - -* In this Page: - * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) - * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) - * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) - - -## Polymorphic Data - -Let's assume, for example, that we have the following inheritance hierarchy: - -![Figure 1: Polymorphic indexes](./assets/polymorphic_indexes_faq.png) - -When saving a `Cat` document, it will be assigned to the "Cats" collection, -while a `Dog` document will be placed in the "Dogs" collection. - -If we intend to create a simple Map-index for Cat documents based on their names, we would write: - - - -{`from cat in docs.Cats -select new \{ cat.Name \} -`} - - - -And for dogs: - - - -{`from dog in docs.Dogs -select new \{ dog.Name \} -`} - - - - -Querying each index results in documents only from the specific collection the index was defined for. -However, what if we need to query across ALL animal collections? - - -## Multi-Map Indexes - -The easiest way to do this is by writing a multi-map index such as: - - - - -{`class Animals_ByName(AbstractMultiMapIndexCreationTask): - def __init__(self): - super().__init__() - self._add_map("from c in docs.Cats select new { c.name }") - self._add_map("from d in docs.Dogs select new { d.name }") -`} - - - - -{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - "map('cats', function (c){ return {Name: c.Name}})", - "map('dogs', function (d){ return {Name: d.Name}})", - } -`} - - - - -And query it like this: - - - - -{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) -`} - - - - -{`from index 'Animals/ByName' -where Name = 'Mitzy' -`} - - - - -## Other Options - -Another option would be to modify the way we generate the Collection for subclasses of `Animal`: - - - -{`store = DocumentStore() - -def _custom_find_collection_name(object_type: Type) -> str: - if issubclass(object_type, Animal): - return "Animals" - return DocumentConventions.default_get_collection_name(object_type) - -store.conventions.find_collection_name = _custom_find_collection_name -`} - - - -Using this method, we can now index on all animals using: - - - -{`from animal in docs.Animals -select new \{ animal.Name \} -`} - - - -But what happens when you don't want to modify the entity name of an entity itself? - -You can create a polymorphic index using: - - - -{`from animal in docs.WhereEntityIs("Cats", "Dogs") -select new \{ animal.Name \} -`} - - - -It will generate an index that matches both Cats and Dogs. - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-related-documents-csharp.mdx b/versioned_docs/version-7.1/indexes/_indexing-related-documents-csharp.mdx deleted file mode 100644 index c176df9eb1..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-related-documents-csharp.mdx +++ /dev/null @@ -1,446 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`public class Products_ByCategoryName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName() - { - Map = products => from product in products - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - let category = LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_JS() - { - Maps = new HashSet() - { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - @"map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -public class Author -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // Referencing a list of related document IDs - public List BookIds \{ get; set; \} -\} - -// The related document -public class Book -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`public class Authors_ByBooks : AbstractIndexCreationTask -{ - public class IndexEntry - { - public IEnumerable BookNames { get; set; } - } - - public Authors_ByBooks() - { - Map = authors => from author in authors - select new IndexEntry - { - // For each Book ID, call LoadDocument and index the book's name - BookNames = author.BookIds.Select(x => LoadDocument(x).Name) - }; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask -{ - public Authors_ByBooks_JS() - { - Maps = new HashSet() - { - // For each Book ID, call 'load' and index the book's name - @"map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = session - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -IList matchingAuthors = await asyncSession - .Query() - .Where(x => x.BookNames.Contains("The Witcher")) - .OfType() - .ToListAsync(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string CategoryName { get; set; } - } - - public Products_ByCategoryName_NoTracking() - { - Map = products => from product in products - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - let category = NoTracking.LoadDocument(product.Category) - - select new IndexEntry - { - // Index the Name field from the related Category document - CategoryName = category.Name - }; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByCategoryName_NoTracking_JS() - { - Maps = new HashSet() - { - // Call 'noTracking.load' to load the related Category document w/o tracking - - @"map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - }; - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`IList matchingProducts = session - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToList(); -`} - - - - -{`IList matchingProducts = await asyncSession - .Query() - .Where(x => x.CategoryName == "Beverages") - .OfType() - .ToListAsync(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-7.1/indexes/_indexing-related-documents-nodejs.mdx deleted file mode 100644 index 65e01214eb..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-related-documents-nodejs.mdx +++ /dev/null @@ -1,398 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - - -#### Example I - basic -**What is tracked**: - -* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - -* Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call LoadDocument to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { load } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - categoryName: load(product.Category, "Categories").Name - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - - - - - -#### Example II - list -**The documents**: - - - -{`// The referencing document -class Author \{ - constructor(id, name, bookIds) \{ - this.id = id; - this.name = name; - - // Referencing a list of related document IDs - this.bookIds = bookIds; - \} -\} -// The related document -class Book \{ - constructor(id, name) \{ - this.id = id; - this.name = name; - \} -\} -`} - - - -**The index**: - -* This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // For each Book ID, call LoadDocument and index the book's name - this.map = \`docs.Authors.Select(author => new { - BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) - })\`; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { load } = this.mapUtils(); - - this.map("Authors", author => { - return { - // For each Book ID, call 'load' and index the book's name - BookNames: author.bookIds.map(x => load(x, "Books").name) - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - }; - }); - } -} -`} - - - - -**The query**: - -* We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - - -{`const matchingProducts = await session - .query({indexName: "Authors/ByBooks"}) - .whereEquals("BookNames", "The Witcher") - .all(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - - - - -#### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - - -#### Example III - no tracking -**What is tracked**: - -* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -**The index**: - - - - -{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { - constructor() { - super(); - - // Call NoTracking.LoadDocument to load the related Category document w/o tracking - this.map = \`docs.Products.Select(product => new { - CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name - })\`; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { noTracking } = this.mapUtils(); - - this.map("Products", product => { - return { - // Call 'noTracking.load' to load the related Category document w/o tracking - categoryName: noTracking.load(product.Category, "Categories").Name - }; - }); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -**The query**: - -* When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`const matchingProducts = await session - .query({indexName: "Products/ByCategoryName/NoTracking"}) - .whereEquals("CategoryName", "Beverages") - .all(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - - - - -#### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - -#### Syntax for LINQ-index: - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-related-documents-php.mdx b/versioned_docs/version-7.1/indexes/_indexing-related-documents-php.mdx deleted file mode 100644 index e9d3a79911..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-related-documents-php.mdx +++ /dev/null @@ -1,491 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} -class Products_ByCategoryName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - 'let category = this.LoadDocument(product.Category, "Categories") ' . - "select new { CategoryName = category.Name }"; - - // Since NoTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call method 'load' to load the related Category document - // The document ID to load is specified by 'product.Category' - // The Name field from the related Category document will be indexed - $this->setMaps([ - "map('products', function(product) { " . - " let category = load(product.Category, 'Categories') " . - " return { " . - " CategoryName: category.Name " . - " }; " . - "})" - ]); - - // Since noTracking was Not specified, - // then any change to either Products or Categories will trigger reindexing - - } -} -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`// The referencing document -class Author -\{ - private ?string $id = null; - private ?string $name = null; - - // Referencing a list of related document IDs - private ?StringArray $bookIds = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} - - public function getBookIds(): ?StringArray - \{ - return $this->bookIds; - \} - - public function setBookIds(?StringArray $bookIds): void - \{ - $this->bookIds = $bookIds; - \} -\} - -// The related document -class Book -\{ - private ?string $id = null; - private ?string $name = null; - - public function getId(): ?string - \{ - return $this->id; - \} - - public function setId(?string $id): void - \{ - $this->id = $id; - \} - - public function getName(): ?string - \{ - return $this->name; - \} - - public function setName(?string $name): void - \{ - $this->name = $name; - \} -\} -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks_IndexEntry -{ - private ?StringArray $bookNames = null; - - public function getBookNames(): ?StringArray - { - return $this->bookNames; - } - - public function setBookNames(?StringArray $bookNames): void - { - $this->bookNames = $bookNames; - } -} -class Authors_ByBooks extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from author in docs.Authors " . - "select new " . - "{" . - // For each Book ID, call LoadDocument and index the book's name - ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . - "}"; - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // For each Book ID, call 'load' and index the book's name - "map('Author', function(author) { - return { - Books: author.BooksIds.map(x => load(x, 'Books').Name) - } - })" - ]); - - // Since NoTracking was Not specified, - // then any change to either Authors or Books will trigger reindexing - } -} -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`// Get all authors that have books with title: "The Witcher" -$matchingAuthors = $session - ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) - ->containsAny("BookNames", ["The Witcher"]) - ->ofType(Author::class) - ->toList(); -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking_IndexEntry -{ - private ?string $categoryName = null; - - public function getCategoryName(): ?string - { - return $this->categoryName; - } - - public function setCategoryName(?string $categoryName): void - { - $this->categoryName = $categoryName; - } -} - -class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from product in docs.Products " . - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . - "select new {" . - # Index the name field from the related Category document - " CategoryName = category.Name " . - "}"; - - // Since NoTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - // Call 'noTracking.load' to load the related Category document w/o tracking - "map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - CategoryName: category.Name - }; - })" - ]); - - // Since noTracking is used - - // then only the changes to Products will trigger reindexing - } -} -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`$matchingProducts = $session - ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) - ->whereEquals("CategoryName", "Beverages") - ->ofType(Product::class) - ->toList(); -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.1/indexes/_indexing-related-documents-python.mdx b/versioned_docs/version-7.1/indexes/_indexing-related-documents-python.mdx deleted file mode 100644 index b89d5a63ca..0000000000 --- a/versioned_docs/version-7.1/indexes/_indexing-related-documents-python.mdx +++ /dev/null @@ -1,381 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), - it is recommended for documents to be: independent, isolated, and coherent. - However, to accommodate varied models, **documents can reference other documents**. - -* The related data from a referenced (related) document can be indexed, - this will allow querying the collection by the indexed related data. - -* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. - -* In this page: - - * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) - - - * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) - * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) - * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) - * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) - * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) - * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) - * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) - * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) - - - -## What are related documents - -* Whenever a document references another document, the referenced document is called a **Related Document**. - -* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, - which are considered Related Documents. - ![Referencing related documents](./assets/index-related-documents.png) - - - -## Index related documents - With tracking - -### Example I - basic - -* **What is tracked**: - Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. - Re-indexing will be triggered per any change in either collection. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - Following the above `Product - Category` relationship from the Northwind sample database, - an index defined on the Products collection can index data from the related Category document. - - - - -{`class Products_ByCategoryName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - 'let category = this.LoadDocument(product.Category, "Categories") ' - "select new { category_name = category.Name }" - ) -`} - - - - -{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call method 'load' to load the related Category document - # The document ID to load is specified by 'product.Category' - # The Name field from the related Category document will be indexed - """ - map('products', function(product) { - let category = load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - # Since no_tracking was not specified, - # then any change to either Products or Categories will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Product documents by `CategoryName`, - i.e. get all matching Products that reference a Category that has the specified name term. - - - - -{`matching_products = list( - session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName" -where CategoryName == "Beverages" -`} - - - -### Example II - list - -* **The documents**: - - -{`# The referencing document -class Author: - def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): - self.Id = Id - self.name = name - - # Referencing a list of related document IDs - self.book_ids = book_ids - - -# The related document -class Book: - def __init__(self, Id: str = None, name: str = None): - self.Id = Id - self.name = name -`} - - - -* **The index**: - This index will index all names of the related Book documents. - - - - -{`class Authors_ByBooks(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, book_names: List[str] = None): - self.book_names = book_names - - def __init__(self): - super().__init__() - self.map = ( - "from author in docs.Authors " - "select new " - "{" - # For each Book ID, call LoadDocument and index the book's name - ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' - "}" - ) - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing -`} - - - - -{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # For each Book ID, call 'load' and index the book's name - """ - map('Author', function(author) { - return { - books: author.BooksIds.map(x => load(x, 'Books').Name) - } - }) - """ - # Since no_tracking was not specified, - # then any change to either Authors or Books will trigger reindexing - } -`} - - - - -* **The query**: - We can now query the index for Author documents by a book's name, - i.e. get all Authors that have the specified book's name in their list. - - - -{`# Get all authors that have books with title: "The Witcher" -matching_authors = list( - session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) - .where_in("book_names", ["The Witcher"]) - .of_type(Author) -) -`} - - - - -{`// Get all authors that have books with title: "The Witcher" -from index "Authors/ByBooks" -where BookNames = "The Witcher" -`} - - - - -### Tracking implications - -* Indexing related data with tracking can be a useful way to query documents by their related data. - However, that may come with performance costs. - -* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. - Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* Frequent re-indexing will increase CPU usage and reduce performance, - and index results may be stale for prolonged periods. - -* Tracking indexed related data is more useful when the indexed related collection is known not to change much. - - - - - -## Index related documents - No tracking - -### Example III - no tracking - -* **What is tracked**: - * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. - Any change done to any document in the **indexed related documents** will Not trigger re-indexing. - (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). - -* **The index**: - - - -{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, category_name: str = None): - self.category_name = category_name - - def __init__(self): - super().__init__() - self.map = ( - "from product in docs.Products " - # Call NoTracking.LoadDocument to load the related Category document w/o tracking - 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' - "select new {" - # Index the name field from the related Category document - " category_name = category.Name " - "}" - ) - # Since NoTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - # Call 'noTracking.load' to load the related Category document w/o tracking - """ - map('products', function(product) { - let category = noTracking.load(product.Category, 'Categories') - return { - category_name: category.Name - }; - }) - """ - } - # Since noTracking is used - - # then only the changes to Products will trigger reindexing -`} - - - - -* **The query**: - When querying the index for Product documents by `CategoryName`, - results will be based on the related data that was **first indexed** when the index was deployed. - - - - -{`matching_products = list( - session.query_index_type( - Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry - ) - .where_equals("category_name", "Beverages") - .of_type(Product) -) -`} - - - - -{`from index "Products/ByCategoryName/NoTracking" -where CategoryName == "Beverages" -`} - - - - -### No-tracking implications - -* Indexing related data with no-tracking can be a useful way to query documents by their related data. - However, that may come with some data accuracy costs. - -* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. - Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. - -* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. - - - - - -## Document changes that cause re-indexing - -* The following changes done to a document will trigger re-indexing: - * Any modification to any document field (not just to the indexed fields) - * Adding/Deleting an attachment - * Creating a new Time series (modifying existing will not trigger) - * Creating a new Counter (modifying existing will not trigger) - -* Any such change done on any document in the **indexed collection** will trigger re-indexing. - -* Any such change done on any document in the **indexed related documents** will trigger re-indexing - only if `NoTracking` was Not used in the index definition. - - - -## LoadDocument syntax - - - -{`T LoadDocument(string relatedDocumentId); - -T LoadDocument(string relatedDocumentId, string relatedCollectionName); - -T[] LoadDocument(IEnumerable relatedDocumentIds); - -T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); -`} - - -#### Syntax for JavaScript-index: - - - -{`object load(relatedDocumentId, relatedCollectionName); -`} - - - -| Parameters | | | -|---------------------------|-----------------------|----------------------------------------| -| **relatedDocumentId** | `string` | ID of the related document to load | -| **relatedCollectionName** | `string` | The related collection name | -| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | - - - - diff --git a/versioned_docs/version-7.1/indexes/_storing-data-in-index-csharp.mdx b/versioned_docs/version-7.1/indexes/_storing-data-in-index-csharp.mdx deleted file mode 100644 index d588e9caf4..0000000000 --- a/versioned_docs/version-7.1/indexes/_storing-data-in-index-csharp.mdx +++ /dev/null @@ -1,409 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB allows you to store data in a static index. - -* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), - without requiring the server to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - -* In this article: - * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) - * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) - * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) - * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) - - -## What content is stored in the index - -* A static index is defined by its map function which determines the content of each **index-entry**. - Typically, a single index-entry is created for each document from the indexed source collection - - unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. - -* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. - The content of an index-field can be a direct value from the source document field, - or a computed value based on the source document's content. - -* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). - The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. - -* **RavenDB allows you to store the original index-field value in the index**. - **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. - * The tokens (terms) generated by the analyzer are searchable but not stored. - * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) - (by default they are not stored). - -* This behavior is supported by both Lucene and Corax search engines. - - - -## When and why to store data in an index - -* **Store a field in the index if**: - - * **You want to project that field without loading the full document.** - Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. - If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. - * **The index-field is a computed value that you want to return in the query results.** - Normally, querying an index returns matching documents. - But if you're projecting a computed index-field that is Not stored, - you'll need to re-calculate the computed value manually from the documents returned by the query. - Storing the computed field avoids this extra step. - -* **You do not need to store a field in the index in order to**: - - * Filter by the field in a query. - * Perform full-text search on the field. - -* **Disadvantage of storing data in the index**: - - * Increased disk space usage - stored fields take up additional space and increase index size. - - - -## Storing data in index - from the Client API - -To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). -The default is `FieldStorage.No`. -**Index example:** - - - - -{`public class QuantityOrdered_ByCompany : - AbstractIndexCreationTask -{ - // The index-entry: - public class IndexEntry - { - // The index-fields: - public string Company { get; set; } - public string CompanyName { get; set; } - public int TotalItemsOrdered { get; set; } - } - - public QuantityOrdered_ByCompany() - { - Map = orders => from order in orders - select new IndexEntry - { - // 'Company' is a SIMPLE index-field, - // its value is taken directly from the Order document: - Company = order.Company, - - // 'CompanyName' is also considered a simple index-field, - // its value is taken from the related Company document: - CompanyName = LoadDocument(order.Company).Name, - - // 'TotalItemsOrdered' is a COMPUTED index-field: - // (the total quantity of items ordered in an Order document) - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }; - - // Store the calculated 'TotalItemsOrdered' index-field in the index: - // ================================================================== - Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); - - // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: - // ======================================================================================= - Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); - - // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): - // ============================================================================= - Stores.Add(x => x.CompanyName, FieldStorage.Yes); - } -} -`} - - - - -{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask -{ - public QuantityOrdered_ByCompany_JS() - { - Maps = new HashSet() - { - @"map('orders', function(order) { - let company = load(order.Company, 'Companies') - return { - Company: order.Company, - CompanyName: company.Name, - TotalItemsOrdered: order.Lines.reduce(function(total, line) { - return total + line.Quantity; - }, 0) - }; - })" - }; - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - }; - } -} -`} - - - - -{`var indexDefinition = new IndexDefinition -{ - Name = "QuantityOrdered/ByCompany", - - Maps = - { - @"from order in docs.Orders - select new - { - Company = order.Company, - CompanyName = LoadDocument(order.Company, ""Companies"").Name, - TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) - }" - }, - - Fields = new Dictionary - { - { - "TotalItemsOrdered", new IndexFieldOptions - { - Storage = FieldStorage.Yes - } - }, - { - "CompanyName", new IndexFieldOptions - { - Storage = FieldStorage.Yes, - Analyzer = "SimpleAnalyzer" - } - } - } -}; - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -**Querying the index and projecting results:** - - - -* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. - -* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. - The server does Not need to load the original document from storage. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List itemsOrdered = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List itemsOrdered = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class NumberOfItemsOrdered -{ - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select TotalItemsOrdered -`} - - - - - - - -* In this query, the projected results are defined by the custom class `ProjectedDetails`. - -* In this case, some of the fields in this class are Not stored in the index, so by default, - the server does need to load the original document from storage to complete the projection. - This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session - .Query() - .Where(order => order.Company == "companies/90-A") - // Project results into a custom class: - .ProjectInto() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession - .Query() - .Where(order => order.Company == "companies/90-A") - .ProjectInto() - .ToListAsync(); -} -`} - - - - -{`using (var session = store.OpenSession()) -{ - List orders = session.Advanced - .DocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToList(); -} -`} - - - - -{`using (var asyncSession = store.OpenAsyncSession()) -{ - List orders = await asyncSession.Advanced - .AsyncDocumentQuery() - .WhereEquals(order => order.Company, "companies/90-A") - .SelectFields() - .ToListAsync(); -} -`} - - - - -{`public class ProjectedDetails -{ - // This field was Not stored in the index definition - public string Company { get; set; } - // This field was Not stored in the index definition - public DateTime OrderedAt { get; set; } - // This field was stored in the index definition - public int TotalItemsOrdered { get; set; } -} -`} - - - - -{`from index "QuantityOrdered/ByCompany" -where Company = "companies/90-A" -select Company, OrderedAt, TotalItemsOrdered -`} - - - - - - - -## Storing data in index - from the Studio - -To configure index-fields from the Studio, open the _Edit Index_ view: - -![The index](./assets/store-field-in-index-1.png) - -1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). -2. These are the index-fields defined in the index map function. -Scroll down to configure each index-field: - -![Configure index fields](./assets/store-field-in-index-2.png) - -1. Open the _Fields_ tab. -2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. -3. Select _Yes_ from the dropdown to store the field in the index. -4. Here we configure index-field `CompanyName`. -5. This index-field is stored in the index and also configured for full-text search. -When querying the index from the Studio, -you can choose to display the stored index fields in the Results view: - -![Display the stored fields](./assets/store-field-in-index-3.png) - -1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). -2. Open the _Settings_ options. -3. Toggle ON _Show stored index fields only_. -4. When executing the query, - the results will display the stored index-fields for each object returned by the query. - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-analyzers-csharp.mdx b/versioned_docs/version-7.1/indexes/_using-analyzers-csharp.mdx deleted file mode 100644 index 0c33a1d29f..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-analyzers-csharp.mdx +++ /dev/null @@ -1,691 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - - 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - - 2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - use the `Analyzers.Add()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`// The index definition -public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string[] Tags { get; set; } - public string Content { get; set; } - } - - public BlogPosts_ByTagsAndContent() - { - Map = posts => from post in posts - select new IndexEntry() - { - Tags = post.Tags, - Content = post.Content - }; - - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - Analyzers.Add(x => x.Content, - typeof(SnowballAnalyzer).AssemblyQualifiedName); - } -} -`} - - - - -{`// The index definition -var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") -{ - Map = posts => from post in posts - select new {post.Tags, post.Content}, - - Analyzers = - { - // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer - {x => x.Tags, "SimpleAnalyzer"}, - - // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer - {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} - } -}.ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `FieldIndexing.Exact` - * `FieldIndexing.Search` - * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`public class BlogPosts_ByContent : AbstractIndexCreationTask -\{ - public BlogPosts_ByContent() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Search' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.Search); - - // => Index-field 'Content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `FieldIndexing.Exact`, - RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask -\{ - public Employees_ByFirstAndLastName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName, - FirstName = employee.FirstName - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.Exact' on index-field 'FirstName' - Indexes.Add(x => x.FirstName, FieldIndexing.Exact); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`public class Employees_ByFirstName : AbstractIndexCreationTask -\{ - public Employees_ByFirstName() - \{ - Map = employees => from employee in employees - select new - \{ - LastName = employee.LastName - \}; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`public class BlogPosts_ByTitle : AbstractIndexCreationTask -\{ - public BlogPosts_ByTitle() - \{ - Map = posts => from post in posts - select new - \{ - Title = post.Title, - Content = post.Content - \}; - - // Set the Indexing Behavior: - // ========================== - - // Set 'FieldIndexing.No' on index-field 'Content' - Indexes.Add(x => x.Content, FieldIndexing.No); - - // Set 'FieldStorage.Yes' to store the original content of field 'Content' - // in the index - Stores.Add(x => x.Content, FieldStorage.Yes); - - // => No analyzer will process field 'Content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) -`} - - - - -{`public class AnalyzerDefinition -\{ - // Name of the analyzer - public string Name \{ get; set; \} - - // C# source-code of the analyzer - public string Code \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`// Define the put analyzer operation: -var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition -\{ - // The name must be same as the analyzer's class name - Name = "MyAnalyzer", - - Code = @" - using System.IO; - using Lucene.Net.Analysis; - using Lucene.Net.Analysis.Standard; - - namespace MyAnalyzer - \{ - public class MyAnalyzer : Lucene.Net.Analysis.Analyzer - \{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - throw new CodeOmitted(); - \} - \} - \}" -\}); - -// Deploy the analyzer: -store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-analyzers-nodejs.mdx b/versioned_docs/version-7.1/indexes/_using-analyzers-nodejs.mdx deleted file mode 100644 index b120b39ea1..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-analyzers-nodejs.mdx +++ /dev/null @@ -1,655 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* RavenDB supports fast and efficient querying through indexes, - which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), - a high-performance search engine developed specifically for RavenDB. - (You can choose which search engine to use for each index). - -* **Analyzers** are components used in the indexing and querying processes of the search engines, - controlling how data is indexed and how search queries interact with the indexed data. - -* **The Corax search engine fully respects and supports all Lucene analyzers**, - ensuring that existing configurations work seamlessly, - while also leveraging Corax's optimized performance for faster query execution. - -* This means you can use any analyzer with either search engine, - giving you full flexibility in configuring your indexes. - -* In this page: - * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) - * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) - * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) - * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) - * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) - * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) - * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) - - -## Understanding the role of analyzers - - - -###### Analyzers in the index definition: -The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. -For each index-field you can specify a particular analyzer to process the content of that field. - - - - -###### Analyzers at indexing time: -During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), -the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. -This is done by the **Analyzers**, which are objects that determine how text is split into tokens. - -Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. -Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words -(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). - -The resulting tokens are then stored in the index for each index-field and can later be searched by queries, -enabling [Full-text search](../indexes/querying/searching.mdx). - - - - -###### Analyzers at query time: -When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), -the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - -When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), -the **same analyzer** used to tokenize field content at indexing time is typically applied -to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. - -There are two exceptions to this rule: - -1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, - it tokenizes the index field at indexing time. - However, at query time, when performing a full-text search on that field, - the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. - - Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, - so to address this issue, you have two options: - * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). - * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. - -2. Behavior is also different when making a full-text search with wildcards in the search terms. - This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). - - - - -###### Full-text search: -In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. -For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). -It is straightforward and may already be available as a contrib package for Lucene. - -You can also configure a specific collation for an index field to sort based on culture specific rules. -Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). - - - - -## Analyzers available in RavenDB - -* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): - - * **StandardAnalyzer** - * **StopAnalyzer** - * **SimpleAnalyzer** - * **WhitespaceAnalyzer** - * **LowerCaseWhitespaceAnalyzer** - * **KeywordAnalyzer** - * **NGramAnalyzer** - -* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). - -* To assign the analyzer of your choice to a specific index-field, - see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). - -* When no analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. - -All examples below use the following text: -`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` - - - -##### Analyzers that remove common "stop words": - - -* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. - * Email addresses and internet hostnames are treated as a single token. - * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. - - - - -* **StopAnalyzer**, which works similarly, will produce the following tokens: - - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Removes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates and tokenizes text based on whitespace without performing light stemming. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - - -* **Stop words**: - - * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) - are often removed to narrow search results by focusing on less frequently used words. - * If you want to include words such as IT (Information Technology), - be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. - This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". - * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it - or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). - - - - - - -##### Analyzers that do not remove common "stop words" - - -* **SimpleAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` - - This analyzer: - - * Includes common "stop words". - * Converts text to lowercase, ensuring searches are case-insensitive. - * Separates on white spaces. - * Will tokenize on all non-alpha characters. - * Removes numbers and symbols, separating tokens at those positions. - This means email and web addresses are split into separate tokens. - - - - -* **WhitespaceAnalyzer** will produce the following tokens: - - `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: - - `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` - - This analyzer: - - * Includes common "stop words". - * Tokenizes text by separating it on whitespaces. - * Converts text to lowercase, ensuring searches are case-insensitive. - * Keeps forms like email addresses, phone numbers, and web addresses whole. - - - - -* **KeywordAnalyzer** will produce the following single token: - - `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - This analyzer: - - * Will perform no tokenization, and will consider the whole text as one token. - * Preserves upper/lower case in text, which means that searches will be case-sensitive. - * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. - - - - - -##### Analyzers that tokenize according to the defined number of characters - - -* **NGramAnalyzer** tokenizes based on predefined token lengths. - - By default, the minimum token length is **2** characters, and the maximum is **6** characters. - Using these defaults, the following tokens will be generated: - - `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] - [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] - [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] - [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] - [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] - [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] - [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] - [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] - [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] - [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] - [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` - -* **Overriding default token length**: (only when using Lucene as the search engine) - - You can override the default token lengths of the NGram analyzer by setting the following configuration keys: - [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) - and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). - - For example, setting them to 3 and 4, respectively, will generate the following tokens: - - `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] - [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] - [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] - [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] - [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` - -* **Querying with NGram analyzer**: - - In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). - However, the `NGramAnalyzer` is an exception to this rule. - - Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. - - - - - -## Setting analyzer for index-field - -* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, - set the `analyze()` method within the index definition for that field. - -* Either: - * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), - * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). - -* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). - -* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). - - - - -{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { - constructor() { - super(); - - this.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content - })\`; - - // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer - this.analyze("tags", "SimpleAnalyzer"); - - // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer - this.analyze("content", "Raven.Sample.SnowballAnalyzer"); - } -} -`} - - - - -{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); -builder.map = \`docs.Posts.Select(post => new { - tags = post.tags, - content = post.content -})\`; -builder.analyzersStrings["tags"] = "SimpleAnalyzer"; -builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; - -await store.maintenance - .send(new PutIndexesOperation( - builder.toIndexDefinition(store.conventions))); -`} - - - - - - -## RavenDB's default analyzers - -* When no specific analyzer is explicitly assigned to an index-field in the index definition, - RavenDB will use the Default Analyzers to process and tokenize the content of the field, - depending on the specified Indexing Behavior. - -* The **Default Analyzers** are: - * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). - * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). - * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). - -* The available **Indexing Behavior** values are: - * `Exact` - * `Search` - * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). - -* See the detailed explanation for each scenario below: - - -##### Using the Default Search Analyzer -* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, - RavenDB will use the Default Search Analyzer. - By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). - -* To customize a different analyzer that will serve as your Default Search Analyzer, - set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. - -* Using a search analyzer enables full-text search queries against the field. - Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: - `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` - - - -{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Search' on index-field 'content' - this.index("content", "Search"); - - // => Index-field 'content' will be processed by the "Default Search Analyzer" - // since no other analyzer is set. - \} -\} -`} - - - - - - -##### Using the Default Exact Analyzer -* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. - By default, this analyzer is the `KeywordAnalyzer`. - -* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, - preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. - The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. - -* To customize a different analyzer that will serve as your Default Exact Analyzer, - set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. - -* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: - `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FirstName = employee.FirstName " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'Exact' on index-field 'FirstName' - this.index("FirstName", "Exact"); - - // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" - \} -\} -`} - - - - - - -##### Using the Default Analyzer -* When no indexing behavior is set and no analyzer is specified for the index-field, - RavenDB will use the Default Analyzer. - By default, this analyzer is the `LowerCaseKeywordAnalyzer`. - -* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. - The entire content of the field is processed into a single, lowercased token. - -* To customize a different analyzer that will serve as your Default Analyzer, - set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. - -* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: - `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` - - - -{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName" + - "\})"; - - // Index-field 'LastName' will be processed by the "Default Analyzer" - // since: - // * No analyzer was specified - // * No Indexing Behavior was specified (neither Exact nor Search) - \} -\} -`} - - - - - - -## Disabling indexing for index-field - -* Use the `No` indexing behavior option to disable indexing of a particular index-field. - In this case: - * No analyzer will process the field, and no terms will be generated from its content. - * The field will not be available for querying. - * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). - -* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. - - - -{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ - constructor() \{ - super(); - - this.map = "docs.Posts.Select(post => new \{ " + - " tags = post.tags, " + - " content = post.content " + - "\})"; - - // Set the Indexing Behavior: - // ========================== - - // Set 'No' on index-field 'content' - this.index("content", "No"); - - // Set 'Yes' to store the original content of field 'content' in the index - this.store("content", "Yes"); - - // => No analyzer will process field 'content', - // it will only be stored in the index. - \} -\} -`} - - - - - -## Creating custom analyzers - -* **Availability & file type**: - The custom analyzer you are referencing must be available to the RavenDB server instance. - You can create and add custom analyzers to RavenDB as `.cs` files. - -* **Scope**: - Custom analyzers can be defined as: - - * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. - * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. - - A database analyzer may have the same name as a server-wide analyzer. - In this case, the indexes of that database will use the database version of the analyzer. - You can think of database analyzers as overriding server-wide analyzers with the same names. - -* **Ways to create**: - There are three ways to create a custom analyzer and add it to your server: - - 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) - 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) - 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) - - -##### Add custom analyzer via Studio - -Custom analyzers can be added from the Custom Analyzers view in the Studio. -Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. - - - - -##### Add custom analyzer via Client API - -First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. -(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). -For example: - - - -{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer -\{ - public override TokenStream TokenStream(string fieldName, TextReader reader) - \{ - // Implement your analyzer's logic - throw new CodeOmitted(); - \} -\} -`} - - - -Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. -By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. -To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. - -To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` - - - -{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); -`} - - - - -{`const analyzerDefinition = \{ - name: "analyzerName", - code: "code" -\}; -`} - - - -| Parameter | Type | Description | -|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | The class name of your custom analyzer, as defined in your code. | -| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | - -**Client API example**: - - - -{`const analyzerDefinition = \{ - name: "MyAnalyzer", - code: "using System.IO;\\n" + - "using Lucene.Net.Analysis;\\n" + - "using Lucene.Net.Analysis.Standard;\\n" + - "\\n" + - "namespace MyAnalyzer\\n" + - "\{\\n" + - " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + - " \{\\n" + - " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + - " \{\\n" + - " throw new CodeOmitted();\\n" + - " \}\\n" + - " \}\\n" + - "\}\\n" -\}; - -await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) -`} - - - - - - -##### Add custom analyzer directly to RavenDB's binaries - -Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. - -The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. - -Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). - -This is the only method for adding custom analyzers in RavenDB versions older than 5.2. - - - - -## Viewing the indexed terms - -The terms generated for each index-field can be viewed in the Studio. - -![The index terms](./assets/index-terms-1.png) - -1. These are the index-fields -2. Click the "Terms" button to view the generated terms for each field - ----- - -![The index terms](./assets/index-terms-2.png) - -1. This is the "index-field name". -2. These are the terms generated for the index-field. - In this example the `StopAnalyzer` was used to tokenize the text. - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-7.1/indexes/_using-dynamic-fields-csharp.mdx deleted file mode 100644 index 30631bba09..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-csharp.mdx +++ /dev/null @@ -1,550 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public Dictionary Attributes \{ get; set; \} -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey : AbstractIndexCreationTask -{ - public Products_ByAttributeKey() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be item.Key - // The actual field terms will be derived from item.Value - _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) - }; - } -} -`} - - - - -{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAttributeKey_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - })" - }; - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - The `_` property is Not queryable but used only in the index definition syntax. - * To get all documents with some 'Size' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - .WhereEquals("Size", 42) - .ToList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public string FirstName \{ get; set; \} - public string LastName \{ get; set; \} - public string Title \{ get; set; \} - // ... -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByAnyField_JS() - { - // This will index EVERY FIELD under the top level of the document - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'LastName' is a dynamic-index-field that was indexed from the document - .WhereEquals("LastName", "Doe") - .ToList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - - // The VALUE of ProductType will be dynamically indexed - public string ProductType \{ get; set; \} - public int PricePerUnit \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType : AbstractIndexCreationTask -{ - public Products_ByProductType() - { - Map = products => from p in products - select new - { - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - _ = CreateField(p.ProductType, p.PricePerUnit) - }; - } -} -`} - - - - -{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask -{ - public Products_ByProductType_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' - .WhereEquals("Electronics", 23) - .ToList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product -\{ - public string Id \{ get; set; \} - public string Name \{ get; set; \} - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public List Attributes \{ get; set; \} -\} - -public class Attribute -\{ - public string PropName \{ get; set; \} - public string PropValue \{ get; set; \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName : AbstractIndexCreationTask -{ - public Attributes_ByName() - { - Map = products => from a in products - select new - { - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), - - // A regular index field can be defined as well: - Name = a.Name - }; - } -} -`} - - - - -{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask -{ - public Attributes_ByName_JS() - { - Maps = new HashSet - { - @"map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - }; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`IList matchingDocuments = session - .Advanced - .DocumentQuery() - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - .WhereEquals("Width", 10) - .ToList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-java.mdx b/versioned_docs/version-7.1/indexes/_using-dynamic-fields-java.mdx deleted file mode 100644 index 2866006674..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-java.mdx +++ /dev/null @@ -1,480 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - private Dictionary attributes; - - // get + set implementation ... -\} -`} - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -* **The index**: - The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAttributeKey_JS() { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + - " { indexing: 'Search', storage: false, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - * To get all documents with some 'size' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAttributeKey_JS.class) - .whereEquals("size", 42) - .toList(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey/JS' where size = 42 -`} - - - - -## Example - index any field - - - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`public class Product \{ - private String id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - private String firstName; - private String lastName; - private String title; - // ... - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - public Products_ByAnyField_JS() { - - // This will index EVERY FIELD under the top level of the document - setMaps(Sets.newHashSet( - "map('Products', function (p) { " + - " return { " + - " _: Object.keys(p).map(key => createField(key, p[key], " + - " { indexing: 'Search', storage: true, termVector: null })) " + - " }; " + - "}) " - )); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'lastName' use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByAnyField_JS.class) - .whereEquals("lastName", "Doe") - .toList(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. - - - -* **The document**: - - -{`public class Product \{ - private String id; - - // The VALUE of productType will be dynamically indexed - private String productType; - private int pricePerUnit; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -* **The index**: - The following index will index the **value** of document field 'productType'. - - This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`public class Products_ByProductType extends AbstractIndexCreationTask { - public Products_ByProductType() { - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`List matchingDocuments = session - .query(Product.class, Products_ByProductType.class) - .whereEquals("Electronics", 23) - .toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`public class Product \{ - private String id; - private String name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - private List attributes; - - // get + set implementation ... -\} - -public class Attribute \{ - private String propName; - private String propValue; - - // get + set implementation ... -\} -`} - - - - - -{`// Sample document content -\{ -name": "SomeName", -attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's propName **value**. - E.g., 'propName' value `Width` will be a dynamic-index-field. - - - - -{`public class Attributes_ByName extends AbstractIndexCreationTask { - public Attributes_ByName() { - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -* **The query**: - * To get all documents matching a specific attribute property use: - - - -{`List matchingDocuments = session - .query(Product.class, Attributes_ByName.class) - .whereEquals("Width", 10) - .toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-7.1/indexes/_using-dynamic-fields-nodejs.mdx deleted file mode 100644 index 9bda34e83c..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-nodejs.mdx +++ /dev/null @@ -1,556 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - - -#### Example - index any field under object -The following allows you to: - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, attributes) \{ - this.id = id; - - // The KEYS under the attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - this.attributes = attributes; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "attributes": \{ - "color": "Red", - "size": 42 - \} -\} -`} - - - -**The index**: - -* The following index will index any field under the `attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the attribute field **key**. - e.g. Keys `color` & `size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // Call 'createField' to generate dynamic-index-fields from the attributes object keys - // Using '_' is just a convention. Any other string can be used instead of '_' - - // The actual field name will be the key - // The actual field terms will be derived from p.attributes[key] - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { - indexing: "Search", - storage: false, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* You can now query the generated dynamic-index fields. - Property `_` is Not queryable, it is only used in the index definition syntax. - -* To get all documents with some 'size' use: - - - - -{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) - // 'size' is a dynamic-index-field that was indexed from the attributes object - .whereEquals('size', 42) - .all(); -`} - - - - -{`// 'size' is a dynamic-index-field that was indexed from the attributes object -from index 'Products/ByAttributeKey' where size = 42 -`} - - - - - - - -#### Example - index any field -The following allows you to: - -* Define an index on a collection **without** needing any common structure between the indexed documents. -* After index is deployed, any new field added to the document will be indexed as well. - - - -Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. - - -**The document**: - - -{`class Product \{ - constructor(id, firstName, lastName, title) \{ - this.id = id; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - this.firstName = firstName; - this.lastName = lastName; - this.title = title; - // ... - \} -\} -`} - - - - - -{`// Sample document content -\{ - "firstName": "John", - "lastName": "Doe", - "title": "Engineer", - // ... -\} -`} - - - -**The index**: - -* The following index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the field **key**. - e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // This will index EVERY FIELD under the top level of the document - _: Object.keys(p).map(key => createField(key, p[key], { - indexing: "Search", - storage: true, - termVector: null - })) - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents with some 'lastName' use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) - // 'lastName' is a dynamic-index-field that was indexed from the document - .whereEquals('lastName', 'Doe') - .all(); -`} - - - - -{`// 'lastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where lastName = "Doe" -`} - - - - - - - - -## Indexing documents fields VALUES - - -#### Example - basic -This example shows: - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. -* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. -**The document**: - - -{`class Product \{ - constructor(id, productType, pricePerUnit) \{ - this.id = id; - - // The VALUE of productType will be dynamically indexed - this.productType = productType; - this.pricePerUnit = pricePerUnit; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "productType": "Electronics", - "pricePerUnit": 23 -\} -`} - - - -**The index**: - -* The following index will index the **value** of document field 'productType'. - -* This value will be the dynamic-index-field name on which you can query. - e.g. Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { - constructor () { - super(); - - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - this.map = "docs.Products.Select(p => new { " + - " _ = this.CreateField(p.productType, p.pricePerUnit) " + - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - _: [ - // The field name will be the value of document field 'productType' - // The field terms will be derived from document field 'pricePerUnit' - createField(p.productType, p.pricePerUnit, { - indexing: "Search", - storage: false, - termVector: null - }) - ] - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents of some product type having a specific price per unit use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) - // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' - .whereEquals('Electronics', 23) - .all(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - - - - -#### Example - list -The following allows you to: - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. -**The document**: - - -{`class Product \{ - constructor(id, name, attributes) \{ - this.id = id; - this.name = name; - - // For each element in this list, the VALUE of property 'propName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - this.attributes = attributes; - \} -\} - -class Attribute \{ - constructor(propName, propValue) \{ - this.propName = propName; - this.propValue = propValue; - \} -\} -`} - - - - - -{`// Sample document content -\{ - "name": "SomeName", - "attributes": [ - \{ - "propName": "Color", - "propValue": "Blue" - \}, - \{ - "propName": "Width", - "propValue": "10" - \}, - \{ - "propName": "Length", - "propValue": "20" - \}, - ... - ] -\} -`} - - - -**The index**: - -* The following index will create a dynamic-index-field per item in the document's `attributes` list. - New items added to the attributes list after index creation time will be dynamically indexed as well. - -* The actual dynamic-index-field name on which you can query will be the item's propName **value**. - e.g. 'propName' value `Width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractCsharpIndexCreationTask -{ - constructor () { - super(); - - // For each attribute item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - // A regular-index-field (Name) is defined as well - this.map = - "docs.Products.Select(p => new { " + - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + - " Name = p.name " + - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - const { createField } = this.mapUtils(); - - this.map("Products", p => { - return { - // For each item, the field name will be the value of field 'propName' - // The field terms will be derived from field 'propValue' - _: p.attributes.map(item => createField(item.propName, item.propValue, { - indexing: "Search", - storage: true, - termVector: null - })), - - // A regular-index-field can be defined as well: - Name: p.name - }; - }); - } -} -`} - - - - -**The query**: - -* To get all documents matching a specific attribute property use: - - - - -{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) - // 'Width' is a dynamic-index-field that was indexed from the attributes list - .whereEquals('Width', 10) - .all(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - - -## CreateField syntax - -#### Syntax for LINQ-index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | Name of the dynamic-index-field | -| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-php.mdx b/versioned_docs/version-7.1/indexes/_using-dynamic-fields-php.mdx deleted file mode 100644 index d57827b1a7..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-php.mdx +++ /dev/null @@ -1,560 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`use Ds\\Map as DSMap; - -class Product -\{ - private ?string $id = null; - - // The KEYS under the Attributes object will be dynamically indexed - // Fields added to this object after index creation time will also get indexed - public ?DSMap $attributes = null; -\} -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "from p in docs.Products select new {" . - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . - "}"; - } -} -`} - - - - -{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { " . - " return { " . - " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . - " { indexing: 'Search', storage: false, termVector: null })) " . - " }; " . - "}) " - ]); - } -} -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAttributeKey::class) - // 'Size' is a dynamic-index-field that was indexed from the Attributes object - ->whereEquals("Size", 42) - ->toList(); -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product -\{ - private ?string $id = null; - - // All KEYS in the document will be dynamically indexed - // Fields added to the document after index creation time will also get indexed - public ?string $firstName = null; - public ?string $lastName = null; - public ?string $title = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // This will index EVERY FIELD under the top level of the document - $this->setMaps([ - "map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByAnyField_JS::class) - // 'LastName' is a dynamic-index-field that was indexed from the document - ->whereEquals("LastName", "Doe") - ->toList(); -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - - // The VALUE of ProductType will be dynamically indexed - public ?string $productType = null; - public ?int $pricePerUnit = null; - - // ... getters and setters -\} -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Call 'CreateField' to generate the dynamic-index-fields - // The field name will be the value of document field 'ProductType' - // The field terms will be derived from document field 'PricePerUnit' - $this->map = "docs.Products.Select(p => new { " . - " _ = this.CreateField(p.productType, p.pricePerUnit) " . - "})"; - } -} -`} - - - - -{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: createField(p.ProductType, p.PricePerUnit, - { indexing: 'Search', storage: true, termVector: null }) - }; - })" - ]); - } -} -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Products_ByProductType::class) -// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -->whereEquals("Electronics", 23) -->toList(); -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Product -\{ - public ?string $id = null; - public ?string $name = null; - - // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed - // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields - public ?AttributeList $attributes = null; - - // ... getters and setters -\} - -class Attribute -\{ - public ?string $propName = null; - public ?string $propValue = null; - - // ... getters and setters -\} - -class AttributeList extends TypedList -\{ - protected function __construct() - \{ - parent::__construct(Attribute::class); - \} -\} -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // Define the dynamic-index-fields by calling CreateField - // A dynamic-index-field will be generated for each item in the Attributes list - - // For each item, the field name will be the value of field 'PropName' - // The field terms will be derived from field 'PropValue' - - $this->map = - "docs.Products.Select(p => new { " . - " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . - " Name = p.name " . - "})"; - } -} -`} - - - - -{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->setMaps([ - "map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - })" - ]); - } -} -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`/** @var array $matchingDocuments */ -$matchingDocuments = $session - ->advanced() - ->documentQuery(Product::class, Attributes_ByName::class) - // 'Width' is a dynamic-index-field that was indexed from the Attributes list - ->whereEquals("Width", 10) - ->toList(); -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing` | | -| **TermVector** | `FieldTermVector` | | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-python.mdx b/versioned_docs/version-7.1/indexes/_using-dynamic-fields-python.mdx deleted file mode 100644 index ffbfebfff6..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-dynamic-fields-python.mdx +++ /dev/null @@ -1,512 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* In RavenDB different documents can have different shapes. - Documents are schemaless - new fields can be added or removed as needed. - -* For such dynamic data, you can define indexes with **dynamic-index-fields**. - -* This allows querying the index on fields that aren't yet known at index creation time, - which is very useful when working on highly dynamic systems. - -* Any value type can be indexed, string, number, date, etc. - -* An index definition can contain both dynamic-index-fields and regular-index-fields. - -* In this page: - - * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) - * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) - * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) - * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) - * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) - * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) - * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) - * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) - - - -## Indexing documents fields KEYS - -## Example - index any field under object - - - -* Index any field that is under the some object from the document. -* After index is deployed, any new field added to the this object will be indexed as well. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, attributes: Dict[str, object] = None): - self.Id = Id - - # The KEYS under the Attributes object will be dynamically indexed - # Fields added to this object after index creation time will also get indexed - self.attributes = attributes -`} - - - - -{`// Sample document content -\{ - "Attributes": \{ - "Color": "Red", - "Size": 42 - \} -\} -`} - - - -* **The index**: - The below index will index any field under the `Attributes` object from the document, - a dynamic-index-field will be created for each such field. - New fields added to the object after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the attribute field **key**. - E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAttributeKey(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from p in docs.Products select new {" - "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" - "}" - ) -`} - - - - -{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], - { indexing: 'Search', storage: true, termVector: null })) - }; - }) - """ - } -`} - - - - - -* **The query**: - * You can now query the generated dynamic-index fields. - * To get all documents with some 'size' use: - - - -{`matching_documents = list( - session.query_index_type(Products_ByAttributeKey, Product) - # 'size' is a dynamic-index-field that was indexed from the attributes object - .where_equals("size", 42) -) -`} - - - - -{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object -from index 'Products/ByAttributeKey' where Size = 42 -`} - - - - -## Example - index any field - - - - * Define an index on a collection **without** needing any common structure between the indexed documents. - * After index is deployed, any new field added to the document will be indexed as well. - - - - -Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): - self.Id = Id - - # All KEYS in the document will be dynamically indexes - # Fields added to the document after index creation time wil also get indexed - self.first_name = first_name - self.last_name = last_name - self.title = title - # ... -`} - - - - - -{`// Sample document content - \{ - "FirstName": "John", - "LastName": "Doe", - "Title": "Engineer", - // ... -\} -`} - - - -* **The index**: - The below index will index any field from the document, - a dynamic-index-field will be created for each field. - New fields added to the document after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the field **key**. - E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. - - - - -{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - # This will index EVERY FIELD under the top level of the document - self.maps = { - """ - map('Products', function (p) { - return { - _: Object.keys(p).map(key => createField(key, p[key], - { indexing: 'Search', storage: true, termVector: null })) - } - }) - """ - } -`} - - - - -* **The query**: - * To get all documents with some 'LastName' use: - - - -{`# 'last_name' is a dynamic-index-field that was indexed from the document -matching_documents = list( - session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") -) -`} - - - - -{`// 'LastName' is a dynamic-index-field that was indexed from the document -from index 'Products/ByAnyField/JS' where LastName = "Doe" -`} - - - - - - -## Indexing documents fields VALUES - -## Example - basic - - - -* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. -* Documents can then be queried based on those indexed values. - - - -* **The document**: - - -{`class Product: - def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): - self.Id = Id - - # The VALUE of ProductType will be dynamically indexed - self.product_type = product_type - self.price_per_unit = price_per_unit -`} - - - - - -{`// Sample document content -\{ - "ProductType": "Electronics", - "PricePerUnit": 23 -\} -`} - - - -* **The index**: - The below index will index the **value** of document field 'ProductType'. - - This value will be the dynamic-index-field name on which you can query. - E.g., Field value `Electronics` will be the dynamic-index-field. - - - - -{`class Products_ByProductType(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - # Call 'CreateField' to generate the dynamic-index-fields - # The field name will be the value of document field 'product_type' - # The field terms will be derived from document field 'price_per_unit' - self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" -`} - - - - -{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: createField(p.product_type, p.price_per_unit, - { indexing: 'Search', storage: true, termVector: null }) - }; - }) - """ - } -`} - - - - -* **The query**: - * To get all documents of some product type having a specific price per unit use: - - - -{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' -matching_documents = list( - session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( - "electronics", 23 - ) -) -`} - - - - -{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' -from index 'Products/ByProductType' where Electronics = 23 -`} - - - - -## Example - list - - - -* Index **values** from items in a list -* After index is deployed, any item added this list in the document will be dynamically indexed as well. - - - -* **The document**: - - -{`class Attribute: - def __init__(self, prop_name: str = None, prop_value: str = None): - self.prop_name = prop_name - self.prop_value = prop_value - - -class Product: - def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): - self.Id = Id - self.name = name - # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed - # e.g. color, width, length (in ex. below) will become dynamic-index-field - self.attributes = attributes -`} - - - - - -{`// Sample document content -\{ -Name": "SomeName", -Attributes": [ - \{ - "PropName": "Color", - "PropValue": "Blue" - \}, - \{ - "PropName": "Width", - "PropValue": "10" - \}, - \{ - "PropName": "Length", - "PropValue": "20" - \}, - ... - -\} -`} - - - -* **The index**: - The below index will create a dynamic-index-field per item in the document's `Attributes` list. - New items added to the Attributes list after index creation time will be dynamically indexed as well. - - The actual dynamic-index-field name on which you can query will be the item's PropName **value**. - E.g., 'PropName' value `width` will be a dynamic-index-field. - - - - -{`class Attributes_ByName(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = ( - "from a in docs.Products select new " - "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " - "}" - ) -`} - - - - -{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): - def __init__(self): - super().__init__() - self.maps = { - """ - map('Products', function (p) { - return { - _: p.Attributes.map(item => createField(item.PropName, item.PropValue, - { indexing: 'Search', storage: true, termVector: null })), - Name: p.Name - }; - }) - """ - } -`} - - - - -* **The query**: - To get all documents matching a specific attribute property use: - - - -{`matching_documents = list( - session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( - "width", 10 - ) -) -`} - - - - -{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list -from index 'Attributes/ByName' where Width = 10 -`} - - - - - - -## CreateField syntax - -#### Syntax for Index: - - - -{`object CreateField(string name, object value); - -object CreateField(string name, object value, bool stored, bool analyzed); - -object CreateField(string name, object value, CreateFieldOptions options); -`} - - - -#### Syntax for JavaScript-index: - - - -{`createField(fieldName, fieldValue, options); // returns object -`} - - - -| Parameters | Type | Description | -|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | `string` | Name of the dynamic-index-field | -| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | -| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | -| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | -| **options** | `CreateFieldOptions` | Dynamic-index-field options | - -| CreateFieldOptions | | | -|--------------------|--------------------|----------------------------------------------------------------------------| -| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | -| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | -| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | - - - -* All above examples have used the character `_` in the dynamic-index-field definition. - However, using `_` is just a convention. Any other string can be used instead. - -* This property is Not queryable, it is only used in the index definition syntax. - The actual dynamic-index-fields that are generated are defined by the `CreateField` method. - - - - - -## Indexed fields & terms view - -The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. -Below are sample index fields & their terms generated from the last example. - -![Figure 1. Go to terms view](./assets/dynamic-index-fields-1.png) - -![Figure 2. Indexed fields & terms](./assets/dynamic-index-fields-2.png) - - - - diff --git a/versioned_docs/version-7.1/indexes/_using-term-vectors-csharp.mdx b/versioned_docs/version-7.1/indexes/_using-term-vectors-csharp.mdx deleted file mode 100644 index cbeea5addd..0000000000 --- a/versioned_docs/version-7.1/indexes/_using-term-vectors-csharp.mdx +++ /dev/null @@ -1,145 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document - as a vector of identifiers. - Lucene indexes can contain term vectors for documents they index. -* Term vectors can be used for various purposes, including similarity searches, information filtering - and retrieval, and indexing. - A book's index, for example, may have term vector enabled on the book's **subject** field, to be able - to use this field to search for books with similar subjects. -* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage - stored term vectors to accomplish their goals. - -* In this page: - * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) - * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) - * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) - - -## Creating an index and enabling Term Vectors on a field - -Indexes that include term vectors can be created and configured using the API -or Studio. - -## Using the API - -To create an index and enable Term Vectors on a specific field, we can - - -A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. -B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). - - - - -{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask -{ - public BlogPosts_ByTagsAndContent() - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }; - - Indexes.Add(x => x.Content, FieldIndexing.Search); - TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); - } -} -`} - - - - -{`IndexDefinitionBuilder indexDefinitionBuilder = - new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") - { - Map = users => from doc in users - select new - { - doc.Tags, - doc.Content - }, - Indexes = - { - { x => x.Content, FieldIndexing.Search } - }, - TermVectors = - { - { x => x.Content, FieldTermVector.WithPositionsAndOffsets } - } - }; - -IndexDefinition indexDefinition = indexDefinitionBuilder - .ToIndexDefinition(store.Conventions); - -store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); -`} - - - - -Available Term Vector options include: - - - -{`public enum FieldTermVector -\{ - /// - /// Do not store term vectors - /// - No, - - /// - /// Store the term vectors of each document. A term vector is a list of the document's - /// terms and their number of occurrences in that document. - /// - Yes, - - /// - /// Store the term vector + token position information - /// - WithPositions, - - /// - /// Store the term vector + Token offset information - /// - WithOffsets, - - /// - /// Store the term vector + Token position and offset information - /// - WithPositionsAndOffsets -\} -`} - - - -Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). - -## Using Studio - -Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector -enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) -can use this fiels to select a product and find products similar to it. - -![Term vector enabled on index field](./assets/term-vector-enabled.png) - -We can now use a query like: - - - -{`from index 'Product/Search' -where morelikethis(id() = 'products/7-A') -`} - - - - - - diff --git a/versioned_docs/version-7.1/indexes/_what-are-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/_what-are-indexes-csharp.mdx deleted file mode 100644 index f784c64ebd..0000000000 --- a/versioned_docs/version-7.1/indexes/_what-are-indexes-csharp.mdx +++ /dev/null @@ -1,235 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public class Employees_ByNameAndCountry : AbstractIndexCreationTask -\{ - public class IndexEntry - \{ - // The index-fields - public string LastName \{ get; set; \} - public string FullName \{ get; set; \} - public string Country \{ get; set; \} - \} - - public Employees_ByNameAndCountry() - \{ - Map = employees => from employee in employees - select new IndexEntry() - \{ - // Define the content for each index-field - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.Country - \}; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `Execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().Execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -IList employeesFromUK = session - .Query() - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .Where(x => x.LastName == "King" && x.Country == "UK") - .OfType() - .ToList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.1/indexes/_what-are-indexes-java.mdx b/versioned_docs/version-7.1/indexes/_what-are-indexes-java.mdx deleted file mode 100644 index bc0dfd5fef..0000000000 --- a/versioned_docs/version-7.1/indexes/_what-are-indexes-java.mdx +++ /dev/null @@ -1,222 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending the `AbstractIndexCreationTask` class. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ - public Employees_ByNameAndCountry() \{ - map = "docs.Employees.Select(employee => new \{ " + - " LastName = employee.LastName, " + - " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + - " Country = employee.Address.Country " + - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -new Employees_ByNameAndCountry().execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -List employeesFromUK = session - .query(Employee.class, Employees_ByNameAndCountry.class) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.1/indexes/_what-are-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/_what-are-indexes-nodejs.mdx deleted file mode 100644 index cdcce58869..0000000000 --- a/versioned_docs/version-7.1/indexes/_what-are-indexes-nodejs.mdx +++ /dev/null @@ -1,229 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`// Define the index: -// ================= - -class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Employees", employee => \{ - return \{ - // Define the content for each index-field: - // ======================================== - LastName: employee.LastName, - FullName: employee.FirstName + " " + employee.LastName, - Country: employee.Address.Country - \}; - \}); - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// Deploy the index to the server: -// =============================== - -const employeesIndex = new Employees_ByNameAndCountry(); -await employeesIndex.execute(store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`// Query the database using the index: -// =================================== - -const employeesFromUK = await session - .query(\{ indexName: employeesIndex.getIndexName() \}) - // Here we query for all Employee documents that are from the UK - // and have 'King' in their LastName field: - .whereEquals("LastName", "King") - .whereEquals("Country", "UK") - .all(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.1/indexes/_what-are-indexes-php.mdx b/versioned_docs/version-7.1/indexes/_what-are-indexes-php.mdx deleted file mode 100644 index 560e0d448d..0000000000 --- a/versioned_docs/version-7.1/indexes/_what-are-indexes-php.mdx +++ /dev/null @@ -1,214 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - $this->map = "docs.Employees.Select(employee => new \{" . - " FirstName = employee.FirstName," . - " LastName = employee.LastName" . - "\})"; - \} -\} -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`// save index on server -(new Employees_ByFirstAndLastName())->execute($store); -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`/** @var array $results */ -$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) - ->whereEquals('FirstName', "Robert") - ->toList(); -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.1/indexes/_what-are-indexes-python.mdx b/versioned_docs/version-7.1/indexes/_what-are-indexes-python.mdx deleted file mode 100644 index 5a3924c991..0000000000 --- a/versioned_docs/version-7.1/indexes/_what-are-indexes-python.mdx +++ /dev/null @@ -1,225 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. - Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. - -* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. - Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), - and many other articles under the "Indexes" menu. - -* In this page: - * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) - * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) - * [Basic example](../indexes/what-are-indexes.mdx#basic-example) - * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) - * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) - - - -## Indexes overview - -**Indexes are fundamental**: - -* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. -* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. - Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). -**Main concepts**: - -* When discussing indexes in RavenDB, three key components come into play: - * The index definition - * The indexing process - * The indexed data - -* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). -**The indexing process**: - -* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. - (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). -* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, - as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. -* A map is built between the indexed-terms and the documents they originated from, - enabling you to query for documents based on the indexed data. -**Automatic data processing**: - -* Once defined and deployed, an index will initially process the entire dataset. - After that, the index will only process documents that were modified, added or deleted. - This happens automatically without requiring direct user intervention. -* For example, if changes are made to documents in the "Orders" collection, - all indexes defined for the "Orders" collection will be triggered to update the index with the new data. -* This approach helps avoid costly table scans, allows the server to respond quickly, - and reduces the load on queries while optimizing machine resource usage. -**Background operation**: - -* RavenDB indexes are designed to run asynchronously in the background. -* The indexing process does not block or interrupt database operations, such as writing data or running queries, - though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. -**Separate storage**: - -* Indexes store their processed data separately, ensuring that the raw data remains unaffected. - This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. - -* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. - Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). - - - -## Types of indexes - -* Indexes in RavenDB are categorized along the following axes: - * **Auto** indexes -vs- **Static** indexes - * **Map** indexes -vs- **Map-Reduce** indexes - * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes - -* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). - - - -## Basic example - -In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). -This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). - - - -#### Define the index - -* The first step is to define the index. - One way to do this is by inheriting from `AbstractIndexCreationTask`. - Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). -* Other methods to create a static-index are: - * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) - * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) - - - -{`# Define the index: -# ================= - -class Employees_ByNameAndCountry(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - - self.map = """ - from employee in docs.Employees - select new \{ - LastName = employee.LastName, - FullName = employee.FirstName + " " + employee.LastName, - Country = employee.Address.country - \} - """ -`} - - - - - - -#### Deploy the index - -* The next step is to deploy the index to the RavenDB server. - One way to do this is by calling `execute()` on the index instance. -* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). -* Once deployed, the indexing process will start indexing documents. - - - -{`# Deploy the index to the server: -# =============================== - -Employees_ByNameAndCountry().execute(store) -`} - - - - - - -#### Query the index - -* Now you can query the _Employees_ collection using the index. - In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. - The results will include only the _Employee_ documents that match the query predicate. -* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). - - - -{`# Query the database using the index: -# =================================== - -employeesFromUK = list( - session.query_index_type(Employees_ByNameAndCountry, Employee) - # Here we query for all Employee documents that are from the UK - # and have 'King' in their LastName field: - .where_equals("Country", "UK") - .where_equals("LastName", "King") -) -`} - - - - - - -## Understanding index query results - - - -A common mistake is treating indexes like SQL Views, but they are not analogous. -The results of a query for a given index are the **full raw documents** that match the query predicate, -and not just the indexed fields. - -This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), -which let you project the query results into selected fields instead of returning the entire document. - - -#### Viewing the resulting documents: - -For example, the results shown in the following image are the **documents** that match the query predicate. - -![Index query results - documents](./assets/index-query-results-1.png) - -1. This is the index query. - The query predicate filters the resulting documents based on the content of the index-fields. -2. Each row in the results represents a **matching document**. -3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. -#### Viewing the index-entries: - -If you wish to **view the index-entries** that compose the index itself, -you can enable the option to show "raw index entries" instead of the matching documents. - -![Index query results - index entries](./assets/index-query-results-2.png) - -1. Query the index (no filtering is applied in this example). -2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". -3. Each row in the results represents an **index-entry**. -4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, - which were defined in the index definition. -5. This a **term**. - In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. - - - -## If indexes exhaust system resources - -* The indexing process utilizes machine resources to keep the data up-to-date for queries. - -* If indexing drains system resources, it may indicate one or more of the following: - * Indexes may have been defined in a way that causes inefficient processing. - * The [license](https://ravendb.net/buy) may need to be upgraded, - * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. - * Hardware upgrades may be necessary to better support your workload. - -* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. - This view provides graphical representations and detailed statistics of all index activities at each stage. - -* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section - for troubleshooting and resolving indexing challenges. - - - - diff --git a/versioned_docs/version-7.1/indexes/boosting.mdx b/versioned_docs/version-7.1/indexes/boosting.mdx index 7afda3c4f5..4384c8e915 100644 --- a/versioned_docs/version-7.1/indexes/boosting.mdx +++ b/versioned_docs/version-7.1/indexes/boosting.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "java", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import BoostingCsharp from './_boosting-csharp.mdx'; -import BoostingJava from './_boosting-java.mdx'; -import BoostingPhp from './_boosting-php.mdx'; -import BoostingNodejs from './_boosting-nodejs.mdx'; +import BoostingCsharp from './content/_boosting-csharp.mdx'; +import BoostingJava from './content/_boosting-java.mdx'; +import BoostingPhp from './content/_boosting-php.mdx'; +import BoostingNodejs from './content/_boosting-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/_boosting-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_boosting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_boosting-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_boosting-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_boosting-java.mdx b/versioned_docs/version-7.1/indexes/content/_boosting-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_boosting-java.mdx rename to versioned_docs/version-7.1/indexes/content/_boosting-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_boosting-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_boosting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_boosting-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_boosting-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_boosting-php.mdx b/versioned_docs/version-7.1/indexes/content/_boosting-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_boosting-php.mdx rename to versioned_docs/version-7.1/indexes/content/_boosting-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_creating-and-deploying-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_creating-and-deploying-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_creating-and-deploying-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_creating-and-deploying-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_creating-and-deploying-java.mdx b/versioned_docs/version-7.1/indexes/content/_creating-and-deploying-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_creating-and-deploying-java.mdx rename to versioned_docs/version-7.1/indexes/content/_creating-and-deploying-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_creating-and-deploying-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_creating-and-deploying-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_creating-and-deploying-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_creating-and-deploying-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_extending-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_extending-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_extending-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_extending-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_extending-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_extending-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_extending-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_extending-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_extending-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_extending-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_extending-indexes-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_extending-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-basics-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-basics-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-basics-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-basics-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-basics-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-basics-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-basics-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-basics-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-basics-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-basics-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-basics-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-basics-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-csharp.mdx new file mode 100644 index 0000000000..0ef9352947 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-csharp.mdx @@ -0,0 +1,247 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`public class BlogPost +\{ + public string Author \{ get; set; \} + public string Title \{ get; set; \} + public string Text \{ get; set; \} + + // Blog post readers can leave comments + public List Comments \{ get; set; \} +\} + +public class BlogPostComment +\{ + public string Author \{ get; set; \} + public string Text \{ get; set; \} + + // Allow nested comments, enabling replies to existing comments + public List Comments \{ get; set; \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _Comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`public class BlogPosts_ByCommentAuthor : + AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor() + { + Map = blogposts => + from blogpost in blogposts + let authors = Recurse(blogpost, x => x.Comments) + select new IndexEntry + { + Authors = authors.Select(x => x.Author) + }; + } +} +`} + + + + +{`public class BlogPosts_ByCommentAuthor_JS : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string[] Authors { get; set; } + } + + public BlogPosts_ByCommentAuthor_JS() + { + Maps = new HashSet + { + @"map('BlogPosts', function (blogpost) { + + var authors = + recurse(blogpost.Comments, function(x) { + return x.Comments; + }) + .filter(function(comment) { + return comment.Author != null; + }) + .map(function(comment) { + return comment.Author; + }); + + return { + Authors: authors + }; + });" + }; + } +} +`} + + + + +{`store.Maintenance.Send(new PutIndexesOperation( + new IndexDefinition + { + Name = "BlogPosts/ByCommentAuthor", + Maps = + { + @"from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.Comments)) + let authorNames = authors.Select(x => x.Author) + select new + { + Authors = authorNames + }" + } + })); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`List results = session + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToList(); +`} + + + + +{`List results = await asyncSession + .Query() + // Query for all blog posts that contain comments by 'Moon': + .Where(x => x.Authors.Any(a => a == "Moon")) + .OfType() + .ToListAsync(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + // Query for all blog posts that contain comments by 'Moon': + .WhereEquals("Authors", "Moon") + .ToList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-hierarchical-data-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-java.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-nodejs.mdx new file mode 100644 index 0000000000..501864a0a4 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-nodejs.mdx @@ -0,0 +1,180 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost \{ + constructor(title, author, text, comments) \{ + this.title = title; + this.author = author; + this.text = text; + + // Blog post readers can leave comments + this.comments = comments; + \} +\} + +class BlogPostComment \{ + constructor(author, text, comments) \{ + this.author = author; + this.text = text; + + // Allow nested comments, enabling replies to existing comments + this.comments = comments; + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "author": "John", + "title": "Post title..", + "text": "Post text..", + "comments": [ + \{ + "author": "Moon", + "text": "Comment text..", + "comments": [ + \{ + "author": "Bob", + "text": "Comment text.." + \}, + \{ + "author": "Adel", + "text": "Comment text..", + "comments": \{ + "author": "Moon", + "text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + this.map = \` + docs.BlogPosts.Select(post => new { + authors = this.Recurse(post, x => x.comments).Select(x0 => x0.author) + })\`; + } +} +`} + + + + +{`const indexDefinition = new IndexDefinition(); + +indexDefinition.name = "BlogPosts/ByCommentAuthor"; +indexDefinition.maps = new Set([ + \`from blogpost in docs.BlogPosts + let authors = Recurse(blogpost, (Func)(x => x.comments)) + let authorNames = authors.Select(x => x.author) + select new + { + Authors = authorNames + }\` +]); + +await store.maintenance.send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`const results = await session + .query({ indexName: "BlogPosts/ByCommentAuthor" }) + // Query for all blog posts that contain comments by 'Moon': + .whereEquals("authors", "Moon") + .all(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from the Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-php.mdx new file mode 100644 index 0000000000..9cf175882a --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-php.mdx @@ -0,0 +1,280 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost +\{ + private ?string $author = null; + private ?string $title = null; + private ?string $text = null; + + // Blog post readers can leave comments + public ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getTitle(): ?string + \{ + return $this->title; + \} + + public function setTitle(?string $title): void + \{ + $this->title = $title; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostComment +\{ + private ?string $author = null; + private ?string $text = null; + + // Comments can be left recursively + private ?BlogPostCommentList $comments = null; + + public function getAuthor(): ?string + \{ + return $this->author; + \} + + public function setAuthor(?string $author): void + \{ + $this->author = $author; + \} + + public function getText(): ?string + \{ + return $this->text; + \} + + public function setText(?string $text): void + \{ + $this->text = $text; + \} + + public function getComments(): ?BlogPostCommentList + \{ + return $this->comments; + \} + + public function setComments(?BlogPostCommentList $comments): void + \{ + $this->comments = $comments; + \} +\} + +class BlogPostCommentList extends TypedList +\{ + public function __construct() + \{ + parent::__construct(BlogPost::class); + \} +\} +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor_Result +{ + private ?StringArray $authors = null; + + public function getAuthors(): ?StringArray + { + return $this->authors; + } + + public function setAuthors(?StringArray $authors): void + { + $this->authors = $authors; + } +} + +class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }"; + } +} +`} + + + + +{`$indexDefinition = new IndexDefinition(); +$indexDefinition->setName("BlogPosts/ByCommentAuthor"); +$indexDefinition->setMaps([ + "from blogpost in docs.BlogPosts + from comment in Recurse(blogpost, (Func)(x => x.Comments)) + select new + { + Author = comment.Author + }" +]); + +$store->maintenance()->send(new PutIndexesOperation($indexDefinition)); +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`/** @var array $results */ +$results = $session + ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "john") + ->ofType(BlogPost::class) + ->toList(); +`} + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class) + ->whereEquals("authors", "John") + ->toList(); +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-python.mdx new file mode 100644 index 0000000000..0d0d310152 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-hierarchical-data-python.mdx @@ -0,0 +1,176 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields. + +* In this Page: + * [Hierarchical data](../indexes/indexing-hierarchical-data.mdx#hierarchical-data) + * [Index hierarchical data](../indexes/indexing-hierarchical-data.mdx#index-hierarchical-data) + * [Query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) + + +## Hierarchical data + +One significant advantage of document databases is their tendency not to impose limits on data structuring. +**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as: + + + +{`class BlogPost: + def __init__(self, author: str = None, title: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.title = title + self.text = text + + # Blog post readers can leave comments + self.comments = comments + + +class BlogPostComment: + def __init__(self, author: str = None, text: str = None, comments: List[BlogPostComment] = None): + self.author = author + self.text = text + + # Allow nested comments, enabling replies to existing comments + self.comments = comments +`} + + + +Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's _comments_ field, +and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure. + +For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors. + +`BlogPosts/1-A`: + + + +{`\{ + "Author": "John", + "Title": "Post title..", + "Text": "Post text..", + "Comments": [ + \{ + "Author": "Moon", + "Text": "Comment text..", + "Comments": [ + \{ + "Author": "Bob", + "Text": "Comment text.." + \}, + \{ + "Author": "Adel", + "Text": "Comment text..", + "Comments": \{ + "Author": "Moon", + "Text": "Comment text.." + \} + \} + ] + \} + ], + "@metadata": \{ + "@collection": "BlogPosts" + \} +\} +`} + + + + + +## Index hierarchical data + +To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method. + +The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors. +We can then [query the index](../indexes/indexing-hierarchical-data.mdx#query-the-index) for all blog posts that contain comments by specific authors. + + + + +{`class BlogPosts_ByCommentAuthor(AbstractIndexCreationTask): + class Result: + def __init__(self, authors: List[str] = None): + self.authors = authors + + def __init__(self): + super().__init__() + self.map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }" +`} + + + + +{`store.maintenance.send( + PutIndexesOperation( + IndexDefinition( + name="BlogPosts/ByCommentAuthor", + maps={ + """from blogpost in docs.BlogPosts + in Recurse(blogpost, (Func)(x => x.comments)) +select new +{ + comment.author +}""" + }, + ) + ) +) +`} + + + + + + +## Query the index + +The index can be queried for all blog posts that contain comments made by specific authors. + +**Query the index using code**: + + + + +{`results = list( + session.query_index_type(BlogPosts_ByCommentAuthor, BlogPosts_ByCommentAuthor.Result).where_equals( + "authors", "Moon" + ) +) +`} + + + + +{`from index "BlogPosts/ByCommentAuthor" +where Authors == "Moon" +`} + + + + +**Query the index using Studio**: + + * Query the index from Studio's [List of Indexes](../studio/database/indexes/indexes-list-view.mdx#indexes-list-view) view: + + !["List of Indexes view"](../assets/list-of-indexes-view.png) + + * View the query results in the [Query](../studio/database/queries/query-view.mdx) view: + + !["Query View"](../assets/query-view.png) + + * View the list of terms indexed by the `Recurse` method: + + !["Click to View Index Terms"](../assets/click-to-view-terms.png) + + !["Index Terms"](../assets/index-terms.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/_indexing-linq-extensions-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-linq-extensions-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-linq-extensions-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-linq-extensions-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-linq-extensions-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-linq-extensions-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-linq-extensions-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-metadata-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-metadata-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-metadata-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-metadata-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-metadata-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-metadata-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-metadata-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-metadata-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-metadata-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-metadata-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-metadata-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-metadata-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-metadata-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-metadata-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-metadata-php.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-metadata-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-metadata-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-metadata-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-metadata-python.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-metadata-python.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-csharp.mdx new file mode 100644 index 0000000000..3a401d0a3b --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-csharp.mdx @@ -0,0 +1,579 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`public class OnlineShop +{ + public string ShopName { get; set; } + public string Email { get; set; } + public List TShirts { get; set; } // Nested data +} + +public class TShirt +{ + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + public decimal Price { get; set; } + public int Sold { get; set; } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var onlineShops = new[] +{ + // Shop1 + new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 }, + new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 }, + new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3} + }}, + // Shop2 + new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List { + new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 }, + new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 } + }}, + // Shop3 + new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List { + new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 }, + new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 }, + new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 }, + new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 } + }} +}; + +using (var session = store.OpenSession()) +{ + foreach (var shop in onlineShops) + { + session.Store(shop); + } + + session.SaveChanges(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`public class Shops_ByTShirt_Simple : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields: + public IEnumerable Colors \{ get; set; \} + public IEnumerable Sizes \{ get; set; \} + public IEnumerable Logos \{ get; set; \} + \} + + public Shops_ByTShirt_Simple() + \{ + Map = shops => from shop in shops + // Creating a SINGLE index-entry per document: + select new IndexEntry + \{ + // Each index-field will hold a collection of nested values from the document + Colors = shop.TShirts.Select(x => x.Color), + Sizes = shop.TShirts.Select(x => x.Size), + Logos = shop.TShirts.Select(x => x.Logo) + \}; + \} +\} +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToList(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = await asyncSession + .Query() + // Filter query results by a nested value + .Where(x => x.Colors.Contains("red")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Query for all shop documents that have a red TShirt +var shopsThatHaveRedShirts = session.Advanced + .DocumentQuery() + // Filter query results by a nested value + .ContainsAny(x => x.Colors, new[] { "Red" }) + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +var GreenAndLarge = session + .Query() + .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L")) + .OfType() + .ToList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public string Size { get; set; } + public string Logo { get; set; } + } + + public Shops_ByTShirt_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + Size = shirt.Size, + Logo = shirt.Logo + }; + } +} +`} + + + + +{`public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask +{ + public Shops_ByTShirt_JS() + { + Maps = new HashSet + { + @"map('OnlineShops', function (shop){ + var res = []; + shop.TShirts.forEach(shirt => { + res.push({ + Color: shirt.Color, + Size: shirt.Size, + Logo: shirt.Logo + }) + }); + return res; + })" + }; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToList(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = await asyncSession + .Query() + // Query for documents that have a "Medium Red TShirt" + .Where(x => x.Color == "red" && x.Size == "M") + .OfType() + .ToListAsync(); +`} + + + + +{`// Query the fanout index: +// ======================= +var shopsThatHaveMediumRedShirts = session.Advanced + .DocumentQuery() + // Query for documents that have a "Medium Red TShirt" + .WhereEquals(x => x.Color, "red") + .AndAlso() + .WhereEquals(x=> x.Size, "M") + .OfType() + .ToList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +public class Sales_ByTShirtColor_Fanout : + AbstractIndexCreationTask +{ + public class IndexEntry + { + // The index-fields: + public string Color { get; set; } + public int ItemsSold { get; set; } + public decimal TotalSales { get; set; } + } + + public Sales_ByTShirtColor_Fanout() + { + Map = shops => + from shop in shops + from shirt in shop.TShirts + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + select new IndexEntry + { + Color = shirt.Color, + ItemsSold = shirt.Sold, + TotalSales = shirt.Price * shirt.Sold + }; + + Reduce = results => from result in results + group result by result.Color + into g + select new + { + // Calculate sales per color + Color = g.Key, + ItemsSold = g.Sum(x => x.ItemsSold), + TotalSales = g.Sum(x => x.TotalSales) + }; + } +} +`} + + + + +{`public class Product_Sales : AbstractJavaScriptIndexCreationTask +{ + public class Result + { + public string Product { get; set; } + + public int Count { get; set; } + + public decimal Total { get; set; } + } + + public Product_Sales() + { + Maps = new HashSet() + { + @"map('orders', function(order){ + var res = []; + order.Lines.forEach(l => { + res.push({ + Product: l.Product, + Count: 1, + Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount) + }) + }); + return res; + })" + }; + + Reduce = @"groupBy(x => x.Product) + .aggregate(g => { + return { + Product : g.key, + Count: g.values.reduce((sum, x) => x.Count + sum, 0), + Total: g.values.reduce((sum, x) => x.Total + sum, 0) + } + })"; + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = await asyncSession + .Query() + // Query for index-entries that contain "black" + .Where(x => x.Color == "black") + .FirstOrDefaultAsync(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`// Query the fanout index: +// ======================= +var queryResult = session.Advanced + .DocumentQuery() + // Query for index-entries that contain "black" + .WhereEquals(x => x.Color, "black") + .FirstOrDefault(); + +// Get total sales for black TShirts +var blackShirtsSales = queryResult?.TotalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490.0 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-java.mdx new file mode 100644 index 0000000000..e9440ef374 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-java.mdx @@ -0,0 +1,131 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The fanout index is the index that outputs multiple index entries per each document. Here is an example of such one: + + + + +{`public static class Orders_ByProduct extends AbstractIndexCreationTask { + public Orders_ByProduct() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, orderLine) => new { " + + " Product = orderLine.Product, " + + " ProductName = orderLine.ProductName " + + "})"; + } +} +`} + + + + +{`public static class Orders_ByProduct extends AbstractJavaScriptIndexCreationTask { + public Orders_ByProduct() { + setMaps(Sets.newHashSet("map('Orders', function (order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " ProductName: l.ProductName\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + "})")); + } +} +`} + + + + +A large order, having a lot of line items, will create an index entry per each `OrderLine` item from the `Lines` collection. A single document can generate hundreds of index entries. + +The fanout index concept is not specific for map-only indexes. It also applies to map-reduce indexes: + + + + +{`public static class Product_Sales extends AbstractIndexCreationTask { + public Product_Sales() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new { " + + " Product = line.Product, " + + " Count = 1, " + + " Total = (((decimal) line.Quantity) * line.PricePerUnit) * (1M - line.Discount) " + + "})"; + + reduce = "results.GroupBy(result => result.Product).Select(g => new {\\n" + + " Product = g.Key,\\n" + + " Count = Enumerable.Sum(g, x => ((int) x.Count)),\\n" + + " Total = Enumerable.Sum(g, x0 => ((decimal) x0.Total))\\n" + + "})"; + } +} +`} + + + + +{`public static class Product_Sales extends AbstractJavaScriptIndexCreationTask { + public Product_Sales() { + setMaps(Sets.newHashSet("map('orders', function(order){\\n" + + " var res = [];\\n" + + " order.Lines.forEach(l => {\\n" + + " res.push({\\n" + + " Product: l.Product,\\n" + + " Count: 1,\\n" + + " Total: (l.Quantity * l.PricePerUnit) * (1- l.Discount)\\n" + + " })\\n" + + " });\\n" + + " return res;\\n" + + " })")); + + setReduce("groupBy(x => x.Product)\\n" + + " .aggregate(g => {\\n" + + " return {\\n" + + " Product : g.key,\\n" + + " Count: g.values.reduce((sum, x) => x.Count + sum, 0),\\n" + + " Total: g.values.reduce((sum, x) => x.Total + sum, 0)\\n" + + " }\\n" + + " })"); + } +} +`} + + + + +The above index definitions are correct. In both cases this is actually what we want. However, you need to be aware that fanout indexes are typically more expensive than regular ones. +RavenDB has to index many more entries than usual. What can result is higher utilization of CPU and memory, and overall declining performance of the index. + + +Starting from version 4.0, the fanout indexes won't error when the number of index entries created from a single document exceeds the configured limit. The configuration options from 3.x: + +- `Raven/MaxSimpleIndexOutputsPerDocument` +- `Raven/MaxMapReduceIndexOutputsPerDocument` + +are no longer valid. + +RavenDB will give you a performance hint regarding high fanout ratio using the Studio's notification center. + + + +## Performance Hints + +Once RavenDB notices that the number of indexing outputs created from a document is high, the notification that will appear in the Studio: + +![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + +The details will give you the following info: + +![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +You can control when a performance hint should be created using the `PerformanceHints.Indexing.MaxIndexOutputsPerDocument` setting (default: 1024). + +## Paging + +Since the fanout index creates multiple entries for a single document and queries return documents by default (it can change if the query defines the projection) the paging of query results +is a bit more complex. Please read the dedicated article about [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results). + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-nodejs.mdx new file mode 100644 index 0000000000..2140ebf2ff --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-nodejs.mdx @@ -0,0 +1,399 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop { + constructor( + shopName = '', + email = '', + tShirts = {} // Will contain the nested data + ) { + Object.assign(this, { shopName, email, tShirts }); + } +} + +class TShirt { + constructor( + color = '', + size = '', + logo = '', + price = 0, + sold = 0 + ) { + Object.assign(this, { color, size, logo, price, sold }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +const bulkInsert = store.bulkInsert(); + +const onlineShops = [ + new OnlineShop("Shop1", "sales@shop1.com", [ + new TShirt("Red", "S", "Bytes and Beyond", 25, 2), + new TShirt("Red", "M", "Bytes and Beyond", 25, 4), + new TShirt("Blue", "M", "Query Everything", 28, 5), + new TShirt("Green", "L", "Data Driver", 30, 3) + ]), + new OnlineShop("Shop2", "sales@shop2.com", [ + new TShirt("Blue", "S", "Coffee, Code, Repeat", 22, 12), + new TShirt("Blue", "M", "Coffee, Code, Repeat", 22, 7), + new TShirt("Green", "M", "Big Data Dreamer", 25, 9), + new TShirt("Black", "L", "Data Mining Expert", 20, 11) + ]), + new OnlineShop("Shop3", "sales@shop3.com", [ + new TShirt("Red", "S", "Bytes of Wisdom", 18, 2), + new TShirt("Blue", "M", "Data Geek", 20, 6), + new TShirt("Black", "L", "Data Revolution", 15, 8), + new TShirt("Black", "XL", "Data Revolution", 15, 10) + ]) +]; + +for (const shop of onlineShops ) { + await bulkInsert.store(shop); +} + +await bulkInsert.finish(); +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating a SINGLE index-entry per document: + this.map("OnlineShops", shop => \{ + return \{ + // Each index-field will hold a collection of nested values from the document + colors: shop.tShirts.map(x => x.color), + sizes: shop.tShirts.map(x => x.size), + logos: shop.tShirts.map(x => x.logo) + \}; + \}); + \} +\} +`} + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +const results = await session + .query({ indexName: "Shops/ByTShirt/Simple" }) + // Filter query results by a nested value + .containsAny("colors", ["red"]) + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `AND` condition. + For example: + + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +const greenAndLarge = await session + .query(\{ indexName: "Shops/ByTShirt/Simple" \}) + .containsAny("colors", ["green"]) + .andAlso() + .containsAny("sizes", ["L"]) + .all(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the tShirts list + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + \}; + \}); + \}); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const shopsThatHaveMediumRedShirts = await session + .query({ indexName: "Shops/ByTShirt/Fanout" }) + // Query for documents that have a "Medium Red TShirt" + .whereEquals("color", "red") + .andAlso() + .whereEquals("size", "M") + .all(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where color == "red" and size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the tShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout extends AbstractJavaScriptIndexCreationTask \{ + constructor () \{ + super(); + + this.map("OnlineShops", shop => \{ + return shop.tShirts.map(shirt => \{ + return \{ + // Define the index-fields: + color: shirt.color, + itemsSold: shirt.sold, + totalSales: shirt.price * shirt.sold + \}; + \}); + \}); + + this.reduce(results => results + .groupBy(shirt => shirt.color) + .aggregate(g => \{ + return \{ + // Calculate sales per color + color: g.key, + itemsSold: g.values.reduce((p, c) => p + c.itemsSold, 0), + totalSales: g.values.reduce((p, c) => p + c.totalSales, 0), + \} + \})); + \} +\} +`} + + + + + + +{`// Query the fanout index: +// ======================= +const queryResult = await session + .query({ indexName: "Sales/ByTShirtColor/Fanout" }) + // Query for index-entries that contain "black" + .whereEquals("color", "black") + .firstOrNull(); + +// Get total sales for black TShirts +const blackShirtsSales = queryResult?.totalSales ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where color == "black" +`} + + + + + + +{`// Query results: +// ============== + +// With the sample data used in this article, +// The total sales revenue from black TShirts sold (in all shops) is 490 +`} + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `totalResults` property (available when calling the query `statistics()` method) + will contain the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-php.mdx new file mode 100644 index 0000000000..d254512f92 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-php.mdx @@ -0,0 +1,624 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop +{ + private ?string $shopName = null; + private ?string $email = null; + public ?TShirtArray $tShirts = null; // Nested data + + public function __construct( + ?string $shopName = null, + ?string $email = null, + ?TShirtArray $tShirts = null + ) { + $this->shopName = $shopName; + $this->email = $email; + $this->tShirts = $tShirts; + } + + public function getShopName(): ?string + { + return $this->shopName; + } + + public function setShopName(?string $shopName): void + { + $this->shopName = $shopName; + } + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getTShirts(): ?TShirtArray + { + return $this->tShirts; + } + + public function setTShirts(?TShirtArray $tShirts): void + { + $this->tShirts = $tShirts; + } +} + +class TShirt +{ + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + private ?float $price = null; + private ?int $sold = null; + + public function __construct( + ?string $color = null, + ?string $size = null, + ?string $logo = null, + ?float $price = null, + ?int $sold = null + ) { + $this->color = $color; + $this->size = $size; + $this->logo = $logo; + $this->price = $price; + $this->sold = $sold; + } + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getSold(): ?int + { + return $this->sold; + } + + public function setSold(?int $sold): void + { + $this->sold = $sold; + } +} + +class TShirtArray extends TypedArray +{ + public function __construct() + { + parent::__construct(TShirt::class); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$onlineShops = []; + +// Shop1 +$onlineShops[] = new OnlineShop( + shopName: "Shop1", + email: "sales@shop1.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes and Beyond", price: 25, sold: 2), + new TShirt(color: "Red", size: "M", logo: "Bytes and Beyond", price: 25, sold: 4), + new TShirt(color: "Blue", size: "M", logo: "Query Everything", price: 28, sold: 5), + new TShirt(color: "Green", size: "L", logo: "Data Driver", price: 30, sold:3) + ]) +); + +// Shop2 +$onlineShops[] = new OnlineShop( + shopName: "Shop2", + email: "sales@shop2.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Blue", size: "S", logo: "Coffee, Code, Repeat", price: 22, sold: 12 ), + new TShirt(color: "Blue", size: "M", logo: "Coffee, Code, Repeat", price: 22, sold: 7 ), + new TShirt(color: "Green", size: "M", logo: "Big Data Dreamer", price: 25, sold: 9 ), + new TShirt(color: "Black", size: "L", logo: "Data Mining Expert", price: 20, sold: 11) + ]) +); + +// Shop3 +$onlineShops[] = new OnlineShop( + shopName: "Shop3", + email: "sales@shop3.com", + tShirts: TShirtArray::fromArray([ + new TShirt(color: "Red", size: "S", logo: "Bytes of Wisdom", price: 18, sold: 2 ), + new TShirt(color: "Blue", size: "M", logo: "Data Geek", price: 20, sold: 6 ), + new TShirt(color: "Black", size: "L", logo: "Data Revolution", price: 15, sold: 8 ), + new TShirt(color: "Black", size: "XL", logo: "Data Revolution", price: 15, sold: 10 ) + ]) +); + +$session = $store->openSession(); +try { + /** @var OnlineShop $shop */ + foreach ($onlineShops as $shop) { + $session->store($shop); + } + + $session->SaveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`_query_1 + // Query for all shop documents that have a red TShirt + $shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`// Query for all shop documents that have a red TShirt +$shopsThatHaveRedShirts = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + // Filter query results by a nested value + ->containsAny("colors", [ "red" ]) + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`// Results will include the following shop documents: +// ================================================== +// * Shop1 +// * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`// You want to query for shops containing "Large Green TShirts", +// aiming to get only "Shop1" as a result since it has such a combination, +// so you attempt this query: +$greenAndLarge = $session + ->query(Shops_ByTShirt_Simple_IndexEntry::class, Shops_ByTShirt_Simple::class) + ->whereEquals("color", "green") + ->andAlso() + ->whereEquals("size", "L") + ->ofType(OnlineShop::class) + ->toList(); + +// But, the results of this query will include BOTH "Shop1" & "Shop2" +// since the index-entries do not keep the original sub-objects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`// A fanout map-index: +// =================== +class Shops_ByTShirt_Fanout_IndexEntry +{ + // The index-fields: + private ?string $color = null; + private ?string $size = null; + private ?string $logo = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getSize(): ?string + { + return $this->size; + } + + public function setSize(?string $size): void + { + $this->size = $size; + } + + public function getLogo(): ?string + { + return $this->logo; + } + + public function setLogo(?string $logo): void + { + $this->logo = $logo; + } +} + +class Shops_ByTShirt_Fanout extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color," . + " size = shirt.size," . + " logo = shirt.logo" . + "}"; + } +} +`} + + + + +{`class Shops_ByTShirt_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + " + ]); + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +$shopsThatHaveMediumRedShirts = $session + ->query(Shops_ByTShirt_Fanout_IndexEntry::class, Shops_ByTShirt_Fanout::class) + // Query for documents that have a "Medium Red TShirt" + ->whereEquals("color", "red") + ->andAlso() + ->whereEquals("size", "M") + ->ofType(OnlineShop::class) + ->toList(); +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`// Query results: +// ============== + +// Only the 'Shop1' document will be returned, +// since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`// A fanout map-reduce index: +// ========================== +class Sales_ByTShirtColor_Fanout_IndexEntry { + // The index-fields: + private ?string $color = null; + private ?int $itemsSold = null; + private ?float $totalSales = null; + + public function getColor(): ?string + { + return $this->color; + } + + public function setColor(?string $color): void + { + $this->color = $color; + } + + public function getItemsSold(): ?int + { + return $this->itemsSold; + } + + public function setItemsSold(?int $itemsSold): void + { + $this->itemsSold = $itemsSold; + } + + public function getTotalSales(): ?float + { + return $this->totalSales; + } + + public function setTotalSales(?float $totalSales): void + { + $this->totalSales = $totalSales; + } +} +class Sales_ByTShirtColor_Fanout extends AbstractIndexCreationTask +{ + + public function __construct() + { + parent::__construct(); + + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + $this->map = + "from shop in docs.OnlineShops " . + "from shirt in shop.t_shirts " . + // Creating MULTIPLE index-entries per document, + // an index-entry for each sub-object in the TShirts list + "select new {" . + " color = shirt.color, " . + " items_sold = shirt.sold, " . + " total_sales = shirt.price * shirt.sold" . + "}"; + + $this->reduce = + "from result in results " . + "group result by result.color " . + "into g select new {" . + " color = g.Key," . + // Calculate sales per color + " items_sold = g.Sum(x => x.items_sold)," . + " total_sales = g.Sum(x => x.total_sales)" . + "}"; + + } +} +`} + + + + + + + +{`// Query the fanout index: +// ======================= +/** @var Sales_ByTShirtColor_Fanout_IndexEntry $queryResult */ +$queryResult = $session + ->query(Sales_ByTShirtColor_Fanout_IndexEntry::class, Sales_ByTShirtColor_Fanout::class) + // Query for index-entries that contain "black" + ->whereEquals("color", "black") + ->firstOrDefault(); + +// Get total sales for black TShirts +$blackShirtsSales = $queryResult?->getTotalSales() ?? 0; +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-python.mdx new file mode 100644 index 0000000000..40065c7f3f --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-nested-data-python.mdx @@ -0,0 +1,444 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* JSON documents can have nested structures, where one document contains other objects or arrays of objects. + +* Use a static-index to facilitate querying for documents based on the nested data. + +* In this page: + + * [Sample data](../indexes/indexing-nested-data.mdx#sample-data) + + * [Simple index - SINGLE index-entry per document](../indexes/indexing-nested-data.mdx#simple-index---single-index-entry-per-document) + * [The index](../indexes/indexing-nested-data.mdx#theIndex) + * [The index-entries](../indexes/indexing-nested-data.mdx#theIndexEntries) + * [Querying the index](../indexes/indexing-nested-data.mdx#queryingTheIndex) + * [When to use](../indexes/indexing-nested-data.mdx#whenToUse) + + * [Fanout index - MULTIPLE index-entries per document](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document) + * [What is a fanout index](../indexes/indexing-nested-data.mdx#whatIsFanoutIndex) + * [Fanout index - Map index example](../indexes/indexing-nested-data.mdx#fanoutMapIndex) + * [Fanout index - Map-Reduce index example](../indexes/indexing-nested-data.mdx#fanoutMapReduceIndex) + * [Performance hints](../indexes/indexing-nested-data.mdx#performanceHints) + * [Paging](../indexes/indexing-nested-data.mdx#paging) + + +## Sample data + +* The examples in this article are based on the following **Classes** and **Sample Data**: + + + + +{`class OnlineShop: + def __init__(self, shop_name: str = None, email: str = None, t_shirts: List[TShirt] = None): + self.shop_name = shop_name + self.email = email + self.t_shirts = t_shirts + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> OnlineShop: + return cls( + json_data["shop_name"], + json_data["email"], + [TShirt.from_json(shirt_json_dict) for shirt_json_dict in json_data["t_shirts"]], + ) + + def to_json(self) -> Dict[str, Any]: + return { + "shop_name": self.shop_name, + "email": self.email, + "t_shirts": [tshirt.to_json() for tshirt in self.t_shirts], + } + + +class TShirt: + def __init__(self, color: str = None, size: str = None, logo: str = None, price: float = None, sold: int = None): + self.color = color + self.size = size + self.logo = logo + self.price = price + self.sold = sold + + @classmethod + def from_json(cls, json_data: Dict[str, Any]) -> TShirt: + return cls(json_data["color"], json_data["size"], json_data["logo"], json_data["price"], json_data["sold"]) + + def to_json(self) -> Dict[str, Any]: + return {"color": self.color, "size": self.size, "logo": self.logo, "price": self.price, "sold": self.sold} +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== +shop1_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes and Beyond", price=25, sold=2), + TShirt(color="Red", size="M", logo="Bytes and Beyond", price=25, sold=4), + TShirt(color="Blue", size="M", logo="Query Everything", price=28, sold=5), + TShirt(color="Green", size="L", logo="Data Driver", price=30, sold=3), +] + +shop2_tshirts = [ + TShirt(color="Blue", size="S", logo="Coffee, Code, Repeat", price=22, sold=12), + TShirt(color="Blue", size="M", logo="Coffee, Code, Repeat", price=22, sold=7), + TShirt(color="Green", size="M", logo="Big Data Dreamer", price=25, sold=9), + TShirt(color="Black", size="L", logo="Data Mining Expert", price=20, sold=11), +] + +shop3_tshirts = [ + TShirt(color="Red", size="S", logo="Bytes of Wisdom", price=18, sold=2), + TShirt(color="Blue", size="M", logo="Data Geek", price=20, sold=6), + TShirt(color="Black", size="L", logo="Data Revolution", price=15, sold=8), + TShirt(color="Black", size="XL", logo="Data Revolution", price=15, sold=10), +] + +online_shops = [ + OnlineShop(shop_name="Shop1", email="sales@shop1.com", t_shirts=shop1_tshirts), + OnlineShop(shop_name="Shop2", email="sales@shop2.com", t_shirts=shop2_tshirts), + OnlineShop(shop_name="Shop3", email="sales@shop3.com", t_shirts=shop3_tshirts), +] + +Shops_ByTShirt_Simple().execute(store) +Shops_ByTShirt_Fanout().execute(store) +Sales_ByTShirtColor_Fanout().execute(store) + +with store.open_session() as session: + for shop in online_shops: + session.store(shop) + + session.save_changes() +`} + + + + + + +## Simple index - Single index-entry per document + +* **The index**: + + +{`class Shops_ByTShirt_Simple(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, colors: List[str] = None, sizes: List[str] = None, logos: List[str] = None): + # The index-fields: + self.colors = colors + self.sizes = sizes + self.logos = logos + + def __init__(self): + super().__init__() + # Creating a SINGLE index-entry per document: + self.map = ( + "from shop in docs.OnlineShops " + "select new \{ " + # Each index-field will hold a collection of nested values from the document + " colors = shop.t_shirts.Select(x => x.color)," + " sizes = shop.t_shirts.Select(x => x.size)," + " logos = shop.t_shirts.Select(x => x.logo)" + "\}" + ) +`} + + + +* **The index-entries**: + + ![Simple - index-entries](../assets/indexing-nested-data-1.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + The index has a single index-entry per document (3 entries in this example). + + 4. The index-field contains a collection of ALL nested values from the document. + e.g. The third **index-entry** has the following values in the _Colors_ **index-field**: + `{"black", "blue", "red"}` + +* **Querying the index**: + + + + +{`# Query for all shop documents that have a red TShirt +shops_that_have_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["Red"]) + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Simple" +where Colors == "red" +`} + + + + + + +{`# Results will include the following shop documents: +# ================================================== +# * Shop1 +# * Shop3 +`} + + + +* **When to use**: + + * This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed. + + * However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain + specific sub-objects which satisfy some `and_also` condition. + For example: + + +{`# You want to query for shops containing "Large Green TShirts", +# aiming to get only "Shop1" as a result since it has such a combination, +# so you attempt this query: +green_and_large = list( + session.query_index_type(Shops_ByTShirt_Simple, Shops_ByTShirt_Simple.IndexEntry) + .contains_any("colors", ["green"]) + .and_also() + .contains_any("sizes", "L") + .of_type(OnlineShop) +) + +# But, the results of this query will include BOTH "Shop1" & "Shop2" +# since the index-queries do not keep the original sub-subjects structure. +`} + + + + * To address this, you must use a **Fanout index** - as described below. + + + +## Fanout index - Multiple index-entries per document + +* **What is a Fanout index**: + + * A fanout index is an index that outputs multiple index-entries per document. + A separate index-entry is created for each nested sub-object from the document. + + * The fanout index is useful when you need to retrieve documents matching query criteria + that search for specific sub-objects that comply with some logical conditions. + +* **Fanout index - Map index example**: + + + + +{`# A fanout map-index: +# =================== +class Shops_ByTShirt_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, size: str = None, logo: str = None): + self.color = color + self.size = size + self.logo = logo + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color," + " size = shirt.size," + " logo = shirt.logo" + "}" + ) +`} + + + + +{`class Shops_ByTShirt_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('OnlineShops', function (shop){ + var res = []; + shop.t_shirts.forEach(shirt => { + res.push({ + color: shirt.color, + size: shirt.size, + logo: shirt.logo + }) + }); + return res; + }) + """ + } +`} + + + + + + + +{`# Query the fanout index: +# ======================= +shops_that_have_medium_red_shirts = list( + session.query_index_type(Shops_ByTShirt_Fanout, Shops_ByTShirt_Fanout.IndexEntry) + # Query for documents that have a "Medium Red TShirt" + .where_equals("color", "red") + .and_also() + .where_equals("size", "M") + .of_type(OnlineShop) +) +`} + + + + +{`from index "Shops/ByTShirt/Fanout" +where Color == "red" and Size == "M" +`} + + + + + + +{`# Query results: +# ============== +# +# Only the 'Shop1' document will be returned, +# since it is the only document that has the requested combination within the TShirt list. +`} + + + +* **The index-entries**: + ![Fanout - index-entries](../assets/indexing-nested-data-2.png) + + 1. The index-entries content is visible from the Studio [Query view](../studio/database/queries/query-view.mdx). + + 2. Check option: _Show raw index-entries instead of Matching documents_. + + 3. Each row represents an **index-entry**. + Each index-entry corresponds to an inner item in the TShirt list. + + 4. In this example, the total number of index-entries is **12**, + which is the total number of inner items in the TShirt list in all **3** documents in the collection. + +* **Fanout index - Map-Reduce index example**: + + * The fanout index concept applies to map-reduce indexes as well: + + + + +{`class Sales_ByTShirtColor_Fanout(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, color: str = None, items_sold: int = None, total_sales: float = None): + self.color = color + self.items_sold = items_sold + self.total_sales = total_sales + + def __init__(self): + super().__init__() + # Creating MULTIPLE index-entries per document, + # an index-entry for each sub-object in the TShirts list + self.map = ( + "from shop in docs.OnlineShops from shirt in shop.t_shirts " + "select new {" + " color = shirt.color, " + " items_sold = shirt.sold, " + " total_sales = shirt.price * shirt.sold" + "}" + ) + self.reduce = ( + "from result in results group result by result.color into g select new {" + " color = g.Key," + " items_sold = g.Sum(x => x.items_sold)," + " total_sales = g.Sum(x => x.total_sales)" + "}" + ) +`} + + + + + + + +{`# Query the fanout index: +# ======================= +query_result = ( + session.query_index_type(Sales_ByTShirtColor_Fanout, Sales_ByTShirtColor_Fanout.IndexEntry) + # Query for index-entries that contain "black" + .where_equals("color", "black").first() +) + +# Get total sales for black TShirts +black_shirts_sales = query_result.total_sales or 0 +`} + + + + +{`from index "Sales/ByTShirtColor/Fanout" +where Color == "black" +`} + + + + +* **Fanout index - Performance hints**: + + * Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries. + This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index. + + * When the number of index-entries generated from a single document exceeds a configurable limit, + RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center. + + * You can control when this performance hint is created by setting the + [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](../server/configuration/performance-hints-configuration.mdx#performancehintsindexingmaxindexoutputsperdocument) configuration key + (default is 1024). + + * So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items + will trigger the following alert: + + ![Figure 1. High indexing fanout ratio notification](../assets/fanout-index-performance-hint-1.png) + + * Clicking the 'Details' button will show the following info: + + ![Figure 2. Fanout index, performance hint details](../assets/fanout-index-performance-hint-2.png) + +* **Fanout index - Paging**: + + * A fanout index has more index-entries than the number of documents in the collection indexed. + Multiple index-entries "point" to the same document from which they originated, + as can be seen in the above [index-entries](../indexes/indexing-nested-data.mdx#fanoutMapIndexIndexEntries) example. + + * When making a fanout index query that should return full documents (without projecting results), + the `TotalResults` property (available via the `QueryStatistics` object) will contain + the total number of index-entries and Not the total number of resulting documents. + + * **To overcome this when paging results**, you must take into account the number of "duplicate" + index-entries that are skipped internally by the server when serving the resulting documents. + + * Please refer to [paging through tampered results](../indexes/querying/paging.mdx#paging-through-tampered-results) for further explanation and examples. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-csharp.mdx new file mode 100644 index 0000000000..15a32e867d --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-csharp.mdx @@ -0,0 +1,167 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`public class Animals_ByName : AbstractMultiMapIndexCreationTask +{ + public Animals_ByName() + { + AddMap(cats => from c in cats select new { c.Name }); + + AddMap(dogs => from d in dogs select new { d.Name }); + } +} +`} + + + + +{`public class Animals_ByName : AbstractJavaScriptIndexCreationTask +{ + public Animals_ByName() + { + Maps = new HashSet() + { + @"map('cats', function (c){ return {Name: c.Name}})", + @"map('dogs', function (d){ return {Name: d.Name}})" + }; + } +} +`} + + + + +And query it like this: + + + + +{`IList results = session + .Query() + .Where(x => x.Name == "Mitzy") + .ToList(); +`} + + + + +{`List results = session + .Advanced + .DocumentQuery() + .WhereEquals("Name", "Mitzy") + .ToList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`DocumentStore store = new DocumentStore() +\{ + Conventions = + \{ + FindCollectionName = type => + \{ + if (typeof(Animal).IsAssignableFrom(type)) + return "Animals"; + return DocumentConventions.DefaultGetCollectionName(type); + \} + \} +\}; +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-java.mdx new file mode 100644 index 0000000000..352a097670 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-java.mdx @@ -0,0 +1,148 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`IndexDefinition indexDefinition = new IndexDefinition(); +indexDefinition.setName("Animals/ByName"); +HashSet maps = new HashSet<>(); +maps.add("docs.Cats.Select(c => new { name = c.name})"); +maps.add("docs.Dogs.Select(c => new { name = c.name})"); +indexDefinition.setMaps(maps); +`} + + + + +{`public static class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + public Animals_ByName() { + setMaps(Sets.newHashSet( + "map('cats', function (c){ return {name: c.name}})", + "map('dogs', function (d){ return {name: d.name}})" + )); + } +} +`} + + + + +And query it like this: + + + + +{`List results = session + .query(Animal.class, Query.index("Animals/ByName")) + .whereEquals("name", "Mitzy") + .toList(); +`} + + + + +{`from index 'Animals/ByName' +where name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`try (IDocumentStore store = new DocumentStore()) \{ + store.getConventions().setFindCollectionName(clazz -> \{ + if (Animal.class.isAssignableFrom(clazz)) \{ + return "Animals"; + \} + + return DocumentConventions.defaultGetCollectionName(clazz); + \}); +\} +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-nodejs.mdx new file mode 100644 index 0000000000..d4630b1f78 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-nodejs.mdx @@ -0,0 +1,297 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this page: + * [The challenge](../indexes/indexing-polymorphic-data.mdx#the-challenge) + * [Possible solutions:](../indexes/indexing-polymorphic-data.mdx#possible-solutions) + * [Multi-map index](../indexes/indexing-polymorphic-data.mdx#multi-map-index) + * [Polymorphic index](../indexes/indexing-polymorphic-data.mdx#polymorphic-index) + * [Customize collection](../indexes/indexing-polymorphic-data.mdx#customize-collection) + + +## The challenge + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +
+**By default**: +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + + +{`class Cats_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Cat extends Animal { } +`} + + + + +And for Dogs: + + + + +{`class Dogs_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index the 'name' field from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +{`class Animal { + constructor(name) { + this.name = name; + } +} + +class Dog extends Animal { } +`} + + + + +**The challenge**: +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + + +## Possible solutions + + + + **Multi-Map Index**: +Writing a [Multi-map index](../indexes/multi-map-indexes.mdx) enables getting results from all collections the index was defined for. + + + + +{`class CatsAndDogs_ByName extends AbstractJavaScriptMultiMapIndexCreationTask { + constructor() { + super(); + + // Index documents from the CATS collection + this.map('Cats', cat => { + return { + name: cat.name + }; + }); + + // Index documents from the DOGS collection + this.map('Dogs', dog => { + return { + name: dog.name + }; + }); + } +} +`} + + + + +Query the Multi-map index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Polymorphic index**: +Another option is to create a polymorphic-index. + +Use method `WhereEntityIs` within your index definition to index documents from all collections +listed in the method. + + + + +{`class CatsAndDogs_ByName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Index documents from both the CATS collection and the DOGS collection + this.map = \`from animal in docs.WhereEntityIs("Cats", "Dogs") + select new { + animal.name + }\`; + } +} +`} + + + + +Query the polymorphic-index: + + + + +{`const catsAndDogs = await session + // Query the index + .query({ indexName: "CatsAndDogs/ByName" }) + // Look for all Cats or Dogs that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the CATS and DOGS collection +`} + + + + +{`from index "CatsAndDogs/ByName" +where name == "Mitzy" +`} + + + + + + + + **Customize collection**: +This option involves customizing the collection name that is assigned to documents created from +subclasses of the _Animal_ class. + +This is done by setting the [findCollectionName](../client-api/configuration/conventions.mdx#findcollectionname) convention on the document store. + + + +{`const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB"); + +// Customize the findCollectionName convention +documentStore.conventions.findCollectionName = (type) => \{ + const typeName = type.name; + + // Documents created from a 'Cat' or a 'Dog' entity will be assinged the "Animals" collection + if (typeName === "Cat" || typeName === "Dog") \{ + return "Animals"; + \} + + // All other documents will be assgined the default collection name + return DocumentConventions.defaultGetCollectionName(type); +\} +`} + + + +With the above convention in place, whenever a _Cat_ or a _Dog_ entity is saved, its document will be assigned the "Animals" collection instead of the default "Cats" or "Dogs" collection. + +Now you can define a Map-index on the "Animals" collection: + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + // Index documents from the ANIMALS collection + this.map('Animals', animal => { + return { + name: animal.name + }; + }); + } +} +`} + + + + +Query the index: + + + + +{`const animals = await session + // Query the index + .query({ indexName: "Animals/ByName" }) + // Look for all Animals that are named 'Mitzy' :)) + .whereEquals("name", "Mitzy") + .all(); + +// Results will include matching documents from the ANIMALS collection +`} + + + + +{`from index "Animals/ByName" +where name == "Mitzy" +`} + + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-php.mdx new file mode 100644 index 0000000000..08abbdc238 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-php.mdx @@ -0,0 +1,158 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName extends AbstractMultiMapIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->addMap("from c in docs.Cats select new { c.name }"); + $this->addMap("from d in docs.Dogs select new { d.name }"); + } +} +`} + + + + +{`class Animals_ByName extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})" + ]); + } +} +`} + + + + +And query it like this: + + + + +{`/** @var array $results */ +$results = $session + ->advanced() + ->documentQuery(Animal::class, Animals_ByName::class) + ->whereEquals("Name", "Mitzy") + ->toList(); +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`$store = new DocumentStore(); +$store->getConventions()->setFindCollectionName( + function (?string $className): string \{ + if (is_a($className, Animal::class)) \{ + return "Animals"; + \} + return DocumentConventions::defaultGetCollectionName($className); + \} +); +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-python.mdx new file mode 100644 index 0000000000..7fbf646f3b --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-polymorphic-data-python.mdx @@ -0,0 +1,142 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* By default, RavenDB indexes are defined on a specific entity type, referred to as a `Collection`, + and do not consider the inheritance hierarchy. + +* In this Page: + * [Polymorphic Data](../indexes/indexing-polymorphic-data.mdx#polymorphic-data) + * [Multi-Map Indexes](../indexes/indexing-polymorphic-data.mdx#multi-map-indexes) + * [Other Options](../indexes/indexing-polymorphic-data.mdx#other-options) + + +## Polymorphic Data + +Let's assume, for example, that we have the following inheritance hierarchy: + +![Figure 1: Polymorphic indexes](../assets/polymorphic_indexes_faq.png) + +When saving a `Cat` document, it will be assigned to the "Cats" collection, +while a `Dog` document will be placed in the "Dogs" collection. + +If we intend to create a simple Map-index for Cat documents based on their names, we would write: + + + +{`from cat in docs.Cats +select new \{ cat.Name \} +`} + + + +And for dogs: + + + +{`from dog in docs.Dogs +select new \{ dog.Name \} +`} + + + + +Querying each index results in documents only from the specific collection the index was defined for. +However, what if we need to query across ALL animal collections? + + +## Multi-Map Indexes + +The easiest way to do this is by writing a multi-map index such as: + + + + +{`class Animals_ByName(AbstractMultiMapIndexCreationTask): + def __init__(self): + super().__init__() + self._add_map("from c in docs.Cats select new { c.name }") + self._add_map("from d in docs.Dogs select new { d.name }") +`} + + + + +{`class Animals_ByName(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + "map('cats', function (c){ return {Name: c.Name}})", + "map('dogs', function (d){ return {Name: d.Name}})", + } +`} + + + + +And query it like this: + + + + +{`results = list(session.query_index_type(Animals_ByName, Animal).where_equals("name", "Mitzy")) +`} + + + + +{`from index 'Animals/ByName' +where Name = 'Mitzy' +`} + + + + +## Other Options + +Another option would be to modify the way we generate the Collection for subclasses of `Animal`: + + + +{`store = DocumentStore() + +def _custom_find_collection_name(object_type: Type) -> str: + if issubclass(object_type, Animal): + return "Animals" + return DocumentConventions.default_get_collection_name(object_type) + +store.conventions.find_collection_name = _custom_find_collection_name +`} + + + +Using this method, we can now index on all animals using: + + + +{`from animal in docs.Animals +select new \{ animal.Name \} +`} + + + +But what happens when you don't want to modify the entity name of an entity itself? + +You can create a polymorphic index using: + + + +{`from animal in docs.WhereEntityIs("Cats", "Dogs") +select new \{ animal.Name \} +`} + + + +It will generate an index that matches both Cats and Dogs. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-csharp.mdx new file mode 100644 index 0000000000..a2c808c053 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-csharp.mdx @@ -0,0 +1,446 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`public class Products_ByCategoryName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName() + { + Map = products => from product in products + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + let category = LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_JS() + { + Maps = new HashSet() + { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + @"map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +public class Author +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // Referencing a list of related document IDs + public List BookIds \{ get; set; \} +\} + +// The related document +public class Book +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`public class Authors_ByBooks : AbstractIndexCreationTask +{ + public class IndexEntry + { + public IEnumerable BookNames { get; set; } + } + + public Authors_ByBooks() + { + Map = authors => from author in authors + select new IndexEntry + { + // For each Book ID, call LoadDocument and index the book's name + BookNames = author.BookIds.Select(x => LoadDocument(x).Name) + }; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`public class Authors_ByBooks_JS : AbstractJavaScriptIndexCreationTask +{ + public Authors_ByBooks_JS() + { + Maps = new HashSet() + { + // For each Book ID, call 'load' and index the book's name + @"map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = session + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +IList matchingAuthors = await asyncSession + .Query() + .Where(x => x.BookNames.Contains("The Witcher")) + .OfType() + .ToListAsync(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`public class Products_ByCategoryName_NoTracking : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string CategoryName { get; set; } + } + + public Products_ByCategoryName_NoTracking() + { + Map = products => from product in products + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + let category = NoTracking.LoadDocument(product.Category) + + select new IndexEntry + { + // Index the Name field from the related Category document + CategoryName = category.Name + }; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`public class Products_ByCategoryName_NoTracking_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByCategoryName_NoTracking_JS() + { + Maps = new HashSet() + { + // Call 'noTracking.load' to load the related Category document w/o tracking + + @"map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + }; + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`IList matchingProducts = session + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToList(); +`} + + + + +{`IList matchingProducts = await asyncSession + .Query() + .Where(x => x.CategoryName == "Beverages") + .OfType() + .ToListAsync(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.1/indexes/_indexing-related-documents-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-related-documents-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-related-documents-java.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-nodejs.mdx new file mode 100644 index 0000000000..41d5bdaefb --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-nodejs.mdx @@ -0,0 +1,398 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + + +#### Example I - basic +**What is tracked**: + +* Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + +* Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call LoadDocument to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { load } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + categoryName: load(product.Category, "Categories").Name + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + + + + + +#### Example II - list +**The documents**: + + + +{`// The referencing document +class Author \{ + constructor(id, name, bookIds) \{ + this.id = id; + this.name = name; + + // Referencing a list of related document IDs + this.bookIds = bookIds; + \} +\} +// The related document +class Book \{ + constructor(id, name) \{ + this.id = id; + this.name = name; + \} +\} +`} + + + +**The index**: + +* This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // For each Book ID, call LoadDocument and index the book's name + this.map = \`docs.Authors.Select(author => new { + BookNames = author.bookIds.Select(x => (this.LoadDocument(x, "Books")).name) + })\`; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { load } = this.mapUtils(); + + this.map("Authors", author => { + return { + // For each Book ID, call 'load' and index the book's name + BookNames: author.bookIds.map(x => load(x, "Books").name) + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + }; + }); + } +} +`} + + + + +**The query**: + +* We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + + +{`const matchingProducts = await session + .query({indexName: "Authors/ByBooks"}) + .whereEquals("BookNames", "The Witcher") + .all(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + + + + +#### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + + +#### Example III - no tracking +**What is tracked**: + +* Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +**The index**: + + + + +{`class Products_ByCategoryName_NoTracking extends AbstractCsharpIndexCreationTask { + constructor() { + super(); + + // Call NoTracking.LoadDocument to load the related Category document w/o tracking + this.map = \`docs.Products.Select(product => new { + CategoryName = (this.NoTracking.LoadDocument(product.Category, "Categories")).Name + })\`; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { noTracking } = this.mapUtils(); + + this.map("Products", product => { + return { + // Call 'noTracking.load' to load the related Category document w/o tracking + categoryName: noTracking.load(product.Category, "Categories").Name + }; + }); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +**The query**: + +* When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`const matchingProducts = await session + .query({indexName: "Products/ByCategoryName/NoTracking"}) + .whereEquals("CategoryName", "Beverages") + .all(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + + + + +#### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + +#### Syntax for LINQ-index: + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-php.mdx new file mode 100644 index 0000000000..9d28e6660b --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-php.mdx @@ -0,0 +1,491 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} +class Products_ByCategoryName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + 'let category = this.LoadDocument(product.Category, "Categories") ' . + "select new { CategoryName = category.Name }"; + + // Since NoTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call method 'load' to load the related Category document + // The document ID to load is specified by 'product.Category' + // The Name field from the related Category document will be indexed + $this->setMaps([ + "map('products', function(product) { " . + " let category = load(product.Category, 'Categories') " . + " return { " . + " CategoryName: category.Name " . + " }; " . + "})" + ]); + + // Since noTracking was Not specified, + // then any change to either Products or Categories will trigger reindexing + + } +} +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_IndexEntry::class, Products_ByCategoryName::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`// The referencing document +class Author +\{ + private ?string $id = null; + private ?string $name = null; + + // Referencing a list of related document IDs + private ?StringArray $bookIds = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} + + public function getBookIds(): ?StringArray + \{ + return $this->bookIds; + \} + + public function setBookIds(?StringArray $bookIds): void + \{ + $this->bookIds = $bookIds; + \} +\} + +// The related document +class Book +\{ + private ?string $id = null; + private ?string $name = null; + + public function getId(): ?string + \{ + return $this->id; + \} + + public function setId(?string $id): void + \{ + $this->id = $id; + \} + + public function getName(): ?string + \{ + return $this->name; + \} + + public function setName(?string $name): void + \{ + $this->name = $name; + \} +\} +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks_IndexEntry +{ + private ?StringArray $bookNames = null; + + public function getBookNames(): ?StringArray + { + return $this->bookNames; + } + + public function setBookNames(?StringArray $bookNames): void + { + $this->bookNames = $bookNames; + } +} +class Authors_ByBooks extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from author in docs.Authors " . + "select new " . + "{" . + // For each Book ID, call LoadDocument and index the book's name + ' BookNames = author.BookIds.Select(x => LoadDocument(x, "Books").Name)' . + "}"; + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +{`class Authors_ByBooks_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // For each Book ID, call 'load' and index the book's name + "map('Author', function(author) { + return { + Books: author.BooksIds.map(x => load(x, 'Books').Name) + } + })" + ]); + + // Since NoTracking was Not specified, + // then any change to either Authors or Books will trigger reindexing + } +} +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`// Get all authors that have books with title: "The Witcher" +$matchingAuthors = $session + ->query(Authors_ByBooks_IndexEntry::class, Authors_ByBooks::class) + ->containsAny("BookNames", ["The Witcher"]) + ->ofType(Author::class) + ->toList(); +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking_IndexEntry +{ + private ?string $categoryName = null; + + public function getCategoryName(): ?string + { + return $this->categoryName; + } + + public function setCategoryName(?string $categoryName): void + { + $this->categoryName = $categoryName; + } +} + +class Products_ByCategoryName_NoTracking extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from product in docs.Products " . + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' . + "select new {" . + # Index the name field from the related Category document + " CategoryName = category.Name " . + "}"; + + // Since NoTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + // Call 'noTracking.load' to load the related Category document w/o tracking + "map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + CategoryName: category.Name + }; + })" + ]); + + // Since noTracking is used - + // then only the changes to Products will trigger reindexing + } +} +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`$matchingProducts = $session + ->query(Products_ByCategoryName_NoTracking_IndexEntry::class, Products_ByCategoryName_NoTracking::class) + ->whereEquals("CategoryName", "Beverages") + ->ofType(Product::class) + ->toList(); +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-python.mdx new file mode 100644 index 0000000000..c312e49e91 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_indexing-related-documents-python.mdx @@ -0,0 +1,381 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* As described in [modeling considerations in RavenDB](https://ravendb.net/learn/inside-ravendb-book/reader/4.0/3-document-modeling#summary), + it is recommended for documents to be: independent, isolated, and coherent. + However, to accommodate varied models, **documents can reference other documents**. + +* The related data from a referenced (related) document can be indexed, + this will allow querying the collection by the indexed related data. + +* The related documents that are loaded in the index definition can be either **Tracked** or **Not-Tracked**. + +* In this page: + + * [What are related documents](../indexes/indexing-related-documents.mdx#what-are-related-documents) + + + * [Index related documents - With tracking](../indexes/indexing-related-documents.mdx#index-related-documents---with-tracking) + * [Example I - basic](../indexes/indexing-related-documents.mdx#example-i---basic) + * [Example II - list](../indexes/indexing-related-documents.mdx#example-ii---list) + * [Tracking implications](../indexes/indexing-related-documents.mdx#tracking-implications) + * [Index related documents - No tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [Example III - no tracking](../indexes/indexing-related-documents.mdx#index-related-documents---no-tracking) + * [No-tracking implications](../indexes/indexing-related-documents.mdx#no-tracking-implications) + * [Document changes that cause re-indexing](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing) + * [LoadDocument Syntax](../indexes/indexing-related-documents.mdx#loaddocument-syntax) + + + +## What are related documents + +* Whenever a document references another document, the referenced document is called a **Related Document**. + +* In the image below, document `products/34-A` references documents `categories/1-A` & `suppliers/16-A`, + which are considered Related Documents. + ![Referencing related documents](../assets/index-related-documents.png) + + + +## Index related documents - With tracking + +### Example I - basic + +* **What is tracked**: + Both the documents from the **indexed collection** and the **indexed related documents** are tracked for changes. + Re-indexing will be triggered per any change in either collection. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + Following the above `Product - Category` relationship from the Northwind sample database, + an index defined on the Products collection can index data from the related Category document. + + + + +{`class Products_ByCategoryName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + 'let category = this.LoadDocument(product.Category, "Categories") ' + "select new { category_name = category.Name }" + ) +`} + + + + +{`class Products_ByCategoryName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call method 'load' to load the related Category document + # The document ID to load is specified by 'product.Category' + # The Name field from the related Category document will be indexed + """ + map('products', function(product) { + let category = load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + # Since no_tracking was not specified, + # then any change to either Products or Categories will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Product documents by `CategoryName`, + i.e. get all matching Products that reference a Category that has the specified name term. + + + + +{`matching_products = list( + session.query_index_type(Products_ByCategoryName, Products_ByCategoryName.IndexEntry) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName" +where CategoryName == "Beverages" +`} + + + +### Example II - list + +* **The documents**: + + +{`# The referencing document +class Author: + def __init__(self, Id: str = None, name: str = None, book_ids: List[str] = None): + self.Id = Id + self.name = name + + # Referencing a list of related document IDs + self.book_ids = book_ids + + +# The related document +class Book: + def __init__(self, Id: str = None, name: str = None): + self.Id = Id + self.name = name +`} + + + +* **The index**: + This index will index all names of the related Book documents. + + + + +{`class Authors_ByBooks(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, book_names: List[str] = None): + self.book_names = book_names + + def __init__(self): + super().__init__() + self.map = ( + "from author in docs.Authors " + "select new " + "{" + # For each Book ID, call LoadDocument and index the book's name + ' book_names = author.book_ids.Select(x => LoadDocument(x, "Books").Name)' + "}" + ) + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing +`} + + + + +{`class Authors_ByBooks_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # For each Book ID, call 'load' and index the book's name + """ + map('Author', function(author) { + return { + books: author.BooksIds.map(x => load(x, 'Books').Name) + } + }) + """ + # Since no_tracking was not specified, + # then any change to either Authors or Books will trigger reindexing + } +`} + + + + +* **The query**: + We can now query the index for Author documents by a book's name, + i.e. get all Authors that have the specified book's name in their list. + + + +{`# Get all authors that have books with title: "The Witcher" +matching_authors = list( + session.query_index_type(Authors_ByBooks, Authors_ByBooks.IndexEntry) + .where_in("book_names", ["The Witcher"]) + .of_type(Author) +) +`} + + + + +{`// Get all authors that have books with title: "The Witcher" +from index "Authors/ByBooks" +where BookNames = "The Witcher" +`} + + + + +### Tracking implications + +* Indexing related data with tracking can be a useful way to query documents by their related data. + However, that may come with performance costs. + +* **Re-indexing** will be triggered whenever any document in the collection that is referenced by `LoadDocument` is changed. + Even when indexing just a single field from the related document, any change to any other field will cause re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* Frequent re-indexing will increase CPU usage and reduce performance, + and index results may be stale for prolonged periods. + +* Tracking indexed related data is more useful when the indexed related collection is known not to change much. + + + + + +## Index related documents - No tracking + +### Example III - no tracking + +* **What is tracked**: + * Only the documents from the **indexed collection** are tracked for changes and can trigger re-indexing. + Any change done to any document in the **indexed related documents** will Not trigger re-indexing. + (See changes that cause re-indexing [here](../indexes/indexing-related-documents.mdx#document-changes-that-cause-re-indexing)). + +* **The index**: + + + +{`class Products_ByCategoryName_NoTracking(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, category_name: str = None): + self.category_name = category_name + + def __init__(self): + super().__init__() + self.map = ( + "from product in docs.Products " + # Call NoTracking.LoadDocument to load the related Category document w/o tracking + 'let category = NoTracking.LoadDocument(product.Category, "Categories") ' + "select new {" + # Index the name field from the related Category document + " category_name = category.Name " + "}" + ) + # Since NoTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +{`class Products_ByCategoryName_NoTracking_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + # Call 'noTracking.load' to load the related Category document w/o tracking + """ + map('products', function(product) { + let category = noTracking.load(product.Category, 'Categories') + return { + category_name: category.Name + }; + }) + """ + } + # Since noTracking is used - + # then only the changes to Products will trigger reindexing +`} + + + + +* **The query**: + When querying the index for Product documents by `CategoryName`, + results will be based on the related data that was **first indexed** when the index was deployed. + + + + +{`matching_products = list( + session.query_index_type( + Products_ByCategoryName_NoTracking, Products_ByCategoryName_NoTracking.IndexEntry + ) + .where_equals("category_name", "Beverages") + .of_type(Product) +) +`} + + + + +{`from index "Products/ByCategoryName/NoTracking" +where CategoryName == "Beverages" +`} + + + + +### No-tracking implications + +* Indexing related data with no-tracking can be a useful way to query documents by their related data. + However, that may come with some data accuracy costs. + +* **Re-indexing** will Not be triggered when documents in the collection that is referenced by `LoadDocument` are changed. + Although this may save system resources, the index entries and the indexed terms may not be updated with the current state of data. + +* Indexing related data without tracking is useful when the indexed related data is fixed and not supposed to change. + + + + + +## Document changes that cause re-indexing + +* The following changes done to a document will trigger re-indexing: + * Any modification to any document field (not just to the indexed fields) + * Adding/Deleting an attachment + * Creating a new Time series (modifying existing will not trigger) + * Creating a new Counter (modifying existing will not trigger) + +* Any such change done on any document in the **indexed collection** will trigger re-indexing. + +* Any such change done on any document in the **indexed related documents** will trigger re-indexing + only if `NoTracking` was Not used in the index definition. + + + +## LoadDocument syntax + + + +{`T LoadDocument(string relatedDocumentId); + +T LoadDocument(string relatedDocumentId, string relatedCollectionName); + +T[] LoadDocument(IEnumerable relatedDocumentIds); + +T[] LoadDocument(IEnumerable relatedDocumentIds, string relatedCollectionName); +`} + + +#### Syntax for JavaScript-index: + + + +{`object load(relatedDocumentId, relatedCollectionName); +`} + + + +| Parameters | | | +|---------------------------|-----------------------|----------------------------------------| +| **relatedDocumentId** | `string` | ID of the related document to load | +| **relatedCollectionName** | `string` | The related collection name | +| **relatedDocumentIds** | `IEnumerable` | A list of related document IDs to load | + + + + diff --git a/versioned_docs/version-7.1/indexes/_indexing-spatial-data-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-spatial-data-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-spatial-data-java.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-spatial-data-java.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-spatial-data-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-spatial-data-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-spatial-data-php.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-spatial-data-php.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_indexing-spatial-data-python.mdx b/versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_indexing-spatial-data-python.mdx rename to versioned_docs/version-7.1/indexes/content/_indexing-spatial-data-python.mdx diff --git a/versioned_docs/version-7.1/indexes/_javascript-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_javascript-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_javascript-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_javascript-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_javascript-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_javascript-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_javascript-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_javascript-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_map-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_map-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-indexes-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_map-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-indexes-php.mdx b/versioned_docs/version-7.1/indexes/content/_map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-indexes-php.mdx rename to versioned_docs/version-7.1/indexes/content/_map-indexes-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-indexes-python.mdx b/versioned_docs/version-7.1/indexes/content/_map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-indexes-python.mdx rename to versioned_docs/version-7.1/indexes/content/_map-indexes-python.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-reduce-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-reduce-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-reduce-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-reduce-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-reduce-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-reduce-indexes-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-reduce-indexes-php.mdx b/versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-reduce-indexes-php.mdx rename to versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_map-reduce-indexes-python.mdx b/versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_map-reduce-indexes-python.mdx rename to versioned_docs/version-7.1/indexes/content/_map-reduce-indexes-python.mdx diff --git a/versioned_docs/version-7.1/indexes/_multi-map-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_multi-map-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_multi-map-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_multi-map-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_multi-map-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_multi-map-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_multi-map-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_multi-map-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_multi-map-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_multi-map-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_multi-map-indexes-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_multi-map-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_multi-map-indexes-php.mdx b/versioned_docs/version-7.1/indexes/content/_multi-map-indexes-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_multi-map-indexes-php.mdx rename to versioned_docs/version-7.1/indexes/content/_multi-map-indexes-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_multi-map-indexes-python.mdx b/versioned_docs/version-7.1/indexes/content/_multi-map-indexes-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_multi-map-indexes-python.mdx rename to versioned_docs/version-7.1/indexes/content/_multi-map-indexes-python.mdx diff --git a/versioned_docs/version-7.1/indexes/_number-type-conversion-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_number-type-conversion-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_number-type-conversion-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_number-type-conversion-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_sorting-and-collation-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_sorting-and-collation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_sorting-and-collation-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_sorting-and-collation-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_sorting-and-collation-java.mdx b/versioned_docs/version-7.1/indexes/content/_sorting-and-collation-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_sorting-and-collation-java.mdx rename to versioned_docs/version-7.1/indexes/content/_sorting-and-collation-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_stale-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_stale-indexes-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_stale-indexes-csharp.mdx rename to versioned_docs/version-7.1/indexes/content/_stale-indexes-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/_stale-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_stale-indexes-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_stale-indexes-java.mdx rename to versioned_docs/version-7.1/indexes/content/_stale-indexes-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_stale-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_stale-indexes-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_stale-indexes-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_stale-indexes-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-csharp.mdx new file mode 100644 index 0000000000..08e46be32f --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-csharp.mdx @@ -0,0 +1,409 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB allows you to store data in a static index. + +* When data is stored in the index, it can be retrieved directly from the index when querying the index and [projecting selected fields](../indexes/querying/projections.mdx), + without requiring the server to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + +* In this article: + * [What content is stored in the index](../indexes/storing-data-in-index.mdx#what-content-is-stored-in-the-index) + * [When and why to store data in an index](../indexes/storing-data-in-index.mdx#when-and-why-to-store-data-in-an-index) + * [Storing data in index - from the Client API](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api) + * [Storing data in index - from the Studio](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-studio) + + +## What content is stored in the index + +* A static index is defined by its map function which determines the content of each **index-entry**. + Typically, a single index-entry is created for each document from the indexed source collection - + unless using a [Fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document), which produces multiple entries per document. + +* Each index-entry consists of a set of **index-fields**, populated with values as defined in the map function. + The content of an index-field can be a direct value from the source document field, + or a computed value based on the source document's content. + +* You can configure an [Analyzer](../indexes/using-analyzers.mdx) (either a custom one or one of RavenDB’s built-in analyzers) to tokenize the content of an index-field for [Full-text search](../indexes/querying/searching.mdx). + The tokens (terms) created by the analyzer form the searchable content of the index. When querying the index, you can filter documents based on these terms. + +* **RavenDB allows you to store the original index-field value in the index**. + **This stored value is the raw content produced by the map function, BEFORE it is tokenized by the analyzer**. + * The tokens (terms) generated by the analyzer are searchable but not stored. + * The index-field values, if explicitly marked as stored, are retrievable when [Projecting index query results](../indexes/querying/projections.mdx) + (by default they are not stored). + +* This behavior is supported by both Lucene and Corax search engines. + + + +## When and why to store data in an index + +* **Store a field in the index if**: + + * **You want to project that field without loading the full document.** + Storing data in a static index allows RavenDB to retrieve that data directly from the index when projecting fields in a query, instead of loading the original document from storage. + If all projected fields are stored, the document will not be loaded - values are fetched directly from the index, resulting in faster projections and better performance. + * **The index-field is a computed value that you want to return in the query results.** + Normally, querying an index returns matching documents. + But if you're projecting a computed index-field that is Not stored, + you'll need to re-calculate the computed value manually from the documents returned by the query. + Storing the computed field avoids this extra step. + +* **You do not need to store a field in the index in order to**: + + * Filter by the field in a query. + * Perform full-text search on the field. + +* **Disadvantage of storing data in the index**: + + * Increased disk space usage - stored fields take up additional space and increase index size. + + + +## Storing data in index - from the Client API + +To store an index-field in a static index, add it to the `Stores` dictionary with `FieldStorage.Yes` in the index definition (this syntax applies to LINQ indexes). +The default is `FieldStorage.No`. +**Index example:** + + + + +{`public class QuantityOrdered_ByCompany : + AbstractIndexCreationTask +{ + // The index-entry: + public class IndexEntry + { + // The index-fields: + public string Company { get; set; } + public string CompanyName { get; set; } + public int TotalItemsOrdered { get; set; } + } + + public QuantityOrdered_ByCompany() + { + Map = orders => from order in orders + select new IndexEntry + { + // 'Company' is a SIMPLE index-field, + // its value is taken directly from the Order document: + Company = order.Company, + + // 'CompanyName' is also considered a simple index-field, + // its value is taken from the related Company document: + CompanyName = LoadDocument(order.Company).Name, + + // 'TotalItemsOrdered' is a COMPUTED index-field: + // (the total quantity of items ordered in an Order document) + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }; + + // Store the calculated 'TotalItemsOrdered' index-field in the index: + // ================================================================== + Stores.Add(x => x.TotalItemsOrdered, FieldStorage.Yes); + + // You can use an analyzer to tokenize the 'CompanyName' index-field for full-text search: + // ======================================================================================= + Analyzers.Add(x => x.CompanyName, "SimpleAnalyzer"); + + // Store the original value of \`CompanyName\` in the index (BEFORE tokenization): + // ============================================================================= + Stores.Add(x => x.CompanyName, FieldStorage.Yes); + } +} +`} + + + + +{`public class QuantityOrdered_ByCompany_JS : AbstractJavaScriptIndexCreationTask +{ + public QuantityOrdered_ByCompany_JS() + { + Maps = new HashSet() + { + @"map('orders', function(order) { + let company = load(order.Company, 'Companies') + return { + Company: order.Company, + CompanyName: company.Name, + TotalItemsOrdered: order.Lines.reduce(function(total, line) { + return total + line.Quantity; + }, 0) + }; + })" + }; + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + }; + } +} +`} + + + + +{`var indexDefinition = new IndexDefinition +{ + Name = "QuantityOrdered/ByCompany", + + Maps = + { + @"from order in docs.Orders + select new + { + Company = order.Company, + CompanyName = LoadDocument(order.Company, ""Companies"").Name, + TotalItemsOrdered = order.Lines.Sum(orderLine => orderLine.Quantity) + }" + }, + + Fields = new Dictionary + { + { + "TotalItemsOrdered", new IndexFieldOptions + { + Storage = FieldStorage.Yes + } + }, + { + "CompanyName", new IndexFieldOptions + { + Storage = FieldStorage.Yes, + Analyzer = "SimpleAnalyzer" + } + } + } +}; + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +**Querying the index and projecting results:** + + + +* In this query, the projected results are defined by the custom class `NumberOfItemsOrdered`. + +* By default, the results will be retrieved from the index, because this class contains a single field `TotalItemsOrdered `, which is stored in the index. + The server does Not need to load the original document from storage. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List itemsOrdered = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List itemsOrdered = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class NumberOfItemsOrdered +{ + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select TotalItemsOrdered +`} + + + + + + + +* In this query, the projected results are defined by the custom class `ProjectedDetails`. + +* In this case, some of the fields in this class are Not stored in the index, so by default, + the server does need to load the original document from storage to complete the projection. + This behavior can be configured at the query level. See [Projection behavior with a static-index](../indexes/querying/projections.mdx#projection-behavior-with-a-static-index) for details. + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session + .Query() + .Where(order => order.Company == "companies/90-A") + // Project results into a custom class: + .ProjectInto() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession + .Query() + .Where(order => order.Company == "companies/90-A") + .ProjectInto() + .ToListAsync(); +} +`} + + + + +{`using (var session = store.OpenSession()) +{ + List orders = session.Advanced + .DocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToList(); +} +`} + + + + +{`using (var asyncSession = store.OpenAsyncSession()) +{ + List orders = await asyncSession.Advanced + .AsyncDocumentQuery() + .WhereEquals(order => order.Company, "companies/90-A") + .SelectFields() + .ToListAsync(); +} +`} + + + + +{`public class ProjectedDetails +{ + // This field was Not stored in the index definition + public string Company { get; set; } + // This field was Not stored in the index definition + public DateTime OrderedAt { get; set; } + // This field was stored in the index definition + public int TotalItemsOrdered { get; set; } +} +`} + + + + +{`from index "QuantityOrdered/ByCompany" +where Company = "companies/90-A" +select Company, OrderedAt, TotalItemsOrdered +`} + + + + + + + +## Storing data in index - from the Studio + +To configure index-fields from the Studio, open the _Edit Index_ view: + +![The index](../assets/store-field-in-index-1.png) + +1. This is the index from the [example above](../indexes/storing-data-in-index.mdx#storing-data-in-index---from-the-client-api). +2. These are the index-fields defined in the index map function. +Scroll down to configure each index-field: + +![Configure index fields](../assets/store-field-in-index-2.png) + +1. Open the _Fields_ tab. +2. Enter the name of the index-field. Here we configure index-field `TotalItemsOrdered`. +3. Select _Yes_ from the dropdown to store the field in the index. +4. Here we configure index-field `CompanyName`. +5. This index-field is stored in the index and also configured for full-text search. +When querying the index from the Studio, +you can choose to display the stored index fields in the Results view: + +![Display the stored fields](../assets/store-field-in-index-3.png) + +1. This is the query from the [example above](../indexes/storing-data-in-index.mdx#query-the-index). +2. Open the _Settings_ options. +3. Toggle ON _Show stored index fields only_. +4. When executing the query, + the results will display the stored index-fields for each object returned by the query. + + + + diff --git a/versioned_docs/version-7.1/indexes/_storing-data-in-index-java.mdx b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_storing-data-in-index-java.mdx rename to versioned_docs/version-7.1/indexes/content/_storing-data-in-index-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_storing-data-in-index-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_storing-data-in-index-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_storing-data-in-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/_storing-data-in-index-php.mdx b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_storing-data-in-index-php.mdx rename to versioned_docs/version-7.1/indexes/content/_storing-data-in-index-php.mdx diff --git a/versioned_docs/version-7.1/indexes/_storing-data-in-index-python.mdx b/versioned_docs/version-7.1/indexes/content/_storing-data-in-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_storing-data-in-index-python.mdx rename to versioned_docs/version-7.1/indexes/content/_storing-data-in-index-python.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_using-analyzers-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_using-analyzers-csharp.mdx new file mode 100644 index 0000000000..ee633b3da5 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-analyzers-csharp.mdx @@ -0,0 +1,691 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + + 1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + + 2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + use the `Analyzers.Add()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`// The index definition +public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string[] Tags { get; set; } + public string Content { get; set; } + } + + public BlogPosts_ByTagsAndContent() + { + Map = posts => from post in posts + select new IndexEntry() + { + Tags = post.Tags, + Content = post.Content + }; + + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + Analyzers.Add(x => x.Tags, "SimpleAnalyzer"); + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + Analyzers.Add(x => x.Content, + typeof(SnowballAnalyzer).AssemblyQualifiedName); + } +} +`} + + + + +{`// The index definition +var indexDefinition = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") +{ + Map = posts => from post in posts + select new {post.Tags, post.Content}, + + Analyzers = + { + // Field 'Tags' will be tokenized by Lucene's SimpleAnalyzer + {x => x.Tags, "SimpleAnalyzer"}, + + // Field 'Content' will be tokenized by the Custom analyzer SnowballAnalyzer + {x => x.Content, typeof(SnowballAnalyzer).AssemblyQualifiedName} + } +}.ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `FieldIndexing.Exact` + * `FieldIndexing.Search` + * `FieldIndexing.No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `FieldIndexing.Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`public class BlogPosts_ByContent : AbstractIndexCreationTask +\{ + public BlogPosts_ByContent() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Search' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.Search); + + // => Index-field 'Content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `FieldIndexing.Exact`, + RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstAndLastName : AbstractIndexCreationTask +\{ + public Employees_ByFirstAndLastName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName, + FirstName = employee.FirstName + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.Exact' on index-field 'FirstName' + Indexes.Add(x => x.FirstName, FieldIndexing.Exact); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`public class Employees_ByFirstName : AbstractIndexCreationTask +\{ + public Employees_ByFirstName() + \{ + Map = employees => from employee in employees + select new + \{ + LastName = employee.LastName + \}; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `FieldIndexing.No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`public class BlogPosts_ByTitle : AbstractIndexCreationTask +\{ + public BlogPosts_ByTitle() + \{ + Map = posts => from post in posts + select new + \{ + Title = post.Title, + Content = post.Content + \}; + + // Set the Indexing Behavior: + // ========================== + + // Set 'FieldIndexing.No' on index-field 'Content' + Indexes.Add(x => x.Content, FieldIndexing.No); + + // Set 'FieldStorage.Yes' to store the original content of field 'Content' + // in the index + Stores.Add(x => x.Content, FieldStorage.Yes); + + // => No analyzer will process field 'Content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [ForDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`public PutAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public PutServerWideAnalyzersOperation(params AnalyzerDefinition[] analyzersToAdd) +`} + + + + +{`public class AnalyzerDefinition +\{ + // Name of the analyzer + public string Name \{ get; set; \} + + // C# source-code of the analyzer + public string Code \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **Code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`// Define the put analyzer operation: +var putAnalyzerOp = new PutAnalyzersOperation(new AnalyzerDefinition +\{ + // The name must be same as the analyzer's class name + Name = "MyAnalyzer", + + Code = @" + using System.IO; + using Lucene.Net.Analysis; + using Lucene.Net.Analysis.Standard; + + namespace MyAnalyzer + \{ + public class MyAnalyzer : Lucene.Net.Analysis.Analyzer + \{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + throw new CodeOmitted(); + \} + \} + \}" +\}); + +// Deploy the analyzer: +store.Maintenance.ForDatabase("MyDatabase").Send(putAnalyzerOp); +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-7.1/indexes/_using-analyzers-java.mdx b/versioned_docs/version-7.1/indexes/content/_using-analyzers-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_using-analyzers-java.mdx rename to versioned_docs/version-7.1/indexes/content/_using-analyzers-java.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_using-analyzers-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_using-analyzers-nodejs.mdx new file mode 100644 index 0000000000..6d96e400e2 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-analyzers-nodejs.mdx @@ -0,0 +1,655 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* RavenDB supports fast and efficient querying through indexes, + which are powered by either [Lucene](http://lucene.apache.org/) or [Corax](../indexes/search-engine/corax.mdx), + a high-performance search engine developed specifically for RavenDB. + (You can choose which search engine to use for each index). + +* **Analyzers** are components used in the indexing and querying processes of the search engines, + controlling how data is indexed and how search queries interact with the indexed data. + +* **The Corax search engine fully respects and supports all Lucene analyzers**, + ensuring that existing configurations work seamlessly, + while also leveraging Corax's optimized performance for faster query execution. + +* This means you can use any analyzer with either search engine, + giving you full flexibility in configuring your indexes. + +* In this page: + * [Understanding the role of analyzers](../indexes/using-analyzers.mdx#understanding-the-role-of-analyzers) + * [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb) + * [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field) + * [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb) + * [Disabling indexing for index-field](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field) + * [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers) + * [Viewing the indexed terms](../indexes/using-analyzers.mdx#viewing-the-indexed-terms) + + +## Understanding the role of analyzers + + + +###### Analyzers in the index definition: +The [index definition](../studio/database/indexes/indexes-overview.mdx#index-definition) determines what content from the documents will be indexed for each index-field. +For each index-field you can specify a particular analyzer to process the content of that field. + + + + +###### Analyzers at indexing time: +During the [indexing process](../studio/database/indexes/indexes-overview.mdx#indexing-process), +the content to be indexed is processed and broken down into smaller components called tokens (or terms) through a process known as **tokenization**. +This is done by the **Analyzers**, which are objects that determine how text is split into tokens. + +Different analyzers vary in how they split the text stream ("tokenize"), and how they process those tokens after tokenization. +Analyzers can apply additional transformations, such as converting text to lowercase, removing stop words +(e.g., "the," "and"), or applying stemming (reducing words to their base forms, e.g., "running" → "run"). + +The resulting tokens are then stored in the index for each index-field and can later be searched by queries, +enabling [Full-text search](../indexes/querying/searching.mdx). + + + + +###### Analyzers at query time: +When running a [Full-text search with a dynamic query](../client-api/session/querying/text-search/full-text-search.mdx), +the auto-index created by the server breaks down the text of the searched document field using the [default search analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + +When running a [Full-text search on a static-index](../indexes/querying/query-index.mdx), +the **same analyzer** used to tokenize field content at indexing time is typically applied +to process the terms provided in the full-text search query before they are sent to the search engine to retrieve matching documents. + +There are two exceptions to this rule: + +1. When setting the [NGramAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-tokenize-according-to-the-defined-number-of-characters) in the index definition, + it tokenizes the index field at indexing time. + However, at query time, when performing a full-text search on that field, + the default [RavenStandardAnalyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer) is used to tokenize the search term from the query predicate. + + Currently, for query time, you cannot specify a different analyzer than the one defined in the index definition, + so to address this issue, you have two options: + * Increase the [MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram) value to generate larger tokens during indexing (when using Lucene). + * Use a different analyzer other than _NGramAnalyzer_ that better matches your requirements. + +2. Behavior is also different when making a full-text search with wildcards in the search terms. + This is explained in detail in [Searching with wildcards](../indexes/querying/searching.mdx#searching-with-wildcards). + + + + +###### Full-text search: +In most cases, Lucene's [StandardAnalyzer](../indexes/using-analyzers.mdx#analyzers-that-remove-common-stop-words) is sufficient for full-text searches. +For languages other than English, or when a custom analysis process is needed, you can provide your own [Custom analyzer](../indexes/using-analyzers.mdx#creating-custom-analyzers). +It is straightforward and may already be available as a contrib package for Lucene. + +You can also configure a specific collation for an index field to sort based on culture specific rules. +Learn more in [Sorting and Collation](../indexes/sorting-and-collation.mdx#collation). + + + + +## Analyzers available in RavenDB + +* RavenDB offers the following Lucene analyzers 'out of the box' (their details are listed below): + + * **StandardAnalyzer** + * **StopAnalyzer** + * **SimpleAnalyzer** + * **WhitespaceAnalyzer** + * **LowerCaseWhitespaceAnalyzer** + * **KeywordAnalyzer** + * **NGramAnalyzer** + +* If needed, you can create your own [Customized Analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers). + +* To assign the analyzer of your choice to a specific index-field, + see: [Setting analyzer for index-field](../indexes/using-analyzers.mdx#setting-analyzer-for-index-field). + +* When no analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use its [Default Analyzers](../indexes/using-analyzers.mdx#ravendb) to process and tokenize the content of a field. + +All examples below use the following text: +`The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.` + + + +##### Analyzers that remove common "stop words": + + +* **StandardAnalyzer**, which is Lucene's default, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on whitespace and punctuation that is followed by whitespace - a dot that is not followed by whitespace is considered part of the token. + * Email addresses and internet hostnames are treated as a single token. + * Splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split. + + + + +* **StopAnalyzer**, which works similarly, will produce the following tokens: + + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Removes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates and tokenizes text based on whitespace without performing light stemming. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + + +* **Stop words**: + + * [Stop words](https://en.wikipedia.org/wiki/Stop_word) (e.g. the, it, a, is, this, who, that...) + are often removed to narrow search results by focusing on less frequently used words. + * If you want to include words such as IT (Information Technology), + be aware that analyzers removing common stop words may treat IT as a stop word and exclude it from the resulting terms. + This can also affect acronyms such as WHO (World Health Organization) or names such as "The Who" or "The IT Crowd". + * To avoid excluding acronyms, you can either spell out the full title instead of abbreviating it + or use an [Analyzer that doesn't remove stop words](../indexes/using-analyzers.mdx#analyzers-that-do-not-remove-common-stop-words). + + + + + + +##### Analyzers that do not remove common "stop words" + + +* **SimpleAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob] [hotmail] [com]` + + This analyzer: + + * Includes common "stop words". + * Converts text to lowercase, ensuring searches are case-insensitive. + * Separates on white spaces. + * Will tokenize on all non-alpha characters. + * Removes numbers and symbols, separating tokens at those positions. + This means email and web addresses are split into separate tokens. + + + + +* **WhitespaceAnalyzer** will produce the following tokens: + + `[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs,] [Bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **LowerCaseWhitespaceAnalyzer** will produce the following tokens: + + `[the] [quick] [brown] [fox] [jumped] [over] [lazy] [dogs,] [bob@hotmail.com] [123432.]` + + This analyzer: + + * Includes common "stop words". + * Tokenizes text by separating it on whitespaces. + * Converts text to lowercase, ensuring searches are case-insensitive. + * Keeps forms like email addresses, phone numbers, and web addresses whole. + + + + +* **KeywordAnalyzer** will produce the following single token: + + `[The quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + This analyzer: + + * Will perform no tokenization, and will consider the whole text as one token. + * Preserves upper/lower case in text, which means that searches will be case-sensitive. + * Useful in situations like IDs and codes where you do not want to separate into multiple tokens. + + + + + +##### Analyzers that tokenize according to the defined number of characters + + +* **NGramAnalyzer** tokenizes based on predefined token lengths. + + By default, the minimum token length is **2** characters, and the maximum is **6** characters. + Using these defaults, the following tokens will be generated: + + `[.c] [.co] [.com] [12] [123] [1234] [12343] [123432] [23] [234] [2343] [23432] + [32] [34] [343] [3432] [43] [432] [@h] [@ho] [@hot] [@hotm] [@hotma] + [ai] [ail] [ail.] [ail.c] [ail.co] [az] [azy] [b@] [b@h] [b@ho] [b@hot] [b@hotm] + [bo] [bob] [bob@] [bob@h] [bob@ho] [br] [bro] [brow] [brown] [ck] [co] [com] + [do] [dog] [dogs] [ed] [er] [fo] [fox] [gs] [ho] [hot] [hotm] [hotma] [hotmai] + [ic] [ick] [il] [il.] [il.c] [il.co] [il.com] [ju] [jum] [jump] [jumpe] [jumped] + [l.] [l.c] [l.co] [l.com] [la] [laz] [lazy] [ma] [mai] [mail] [mail.] [mail.c] + [mp] [mpe] [mped] [ob] [ob@] [ob@h] [ob@ho] [ob@hot] [og] [ogs] [om] [ot] [otm] + [otma] [otmai] [otmail] [ov] [ove] [over] [ow] [own] [ox] [pe] [ped] [qu] [qui] + [quic] [quick] [ro] [row] [rown] [tm] [tma] [tmai] [tmail] [tmail.] + [ui] [uic] [uick] [um] [ump] [umpe] [umped] [ve] [ver] [wn] [zy]` + +* **Overriding default token length**: (only when using Lucene as the search engine) + + You can override the default token lengths of the NGram analyzer by setting the following configuration keys: + [Indexing.Lucene.Analyzers.NGram.MinGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammingram) + and [Indexing.Lucene.Analyzers.NGram.MaxGram](../server/configuration/indexing-configuration.mdx#indexingluceneanalyzersngrammaxgram). + + For example, setting them to 3 and 4, respectively, will generate the following tokens: + + `[.co] [.com] [123] [1234] [234] [2343] [343] [3432] [432] [@ho] [@hot] + [ail] [ail.] [azy] [b@h] [b@ho] [bob] [bob@] [bro] [brow] [com] [dog] [dogs] [fox] + [hot] [hotm] [ick] [il.] [il.c] [jum] [jump] [l.c] [l.co] [laz] [lazy] [mai] [mail] + [mpe] [mped] [ob@] [ob@h] [ogs] [otm] [otma] [ove] [over] [own] [ped] [qui] [quic] + [row] [rown] [tma] [tmai] [uic] [uick] [ump] [umpe] [ver]` + +* **Querying with NGram analyzer**: + + In RavenDB, the analyzer configured in the index definition is typically used both at indexing time and query time (the same analyzer). + However, the `NGramAnalyzer` is an exception to this rule. + + Refer to section [Analyzers at query time](../indexes/using-analyzers.mdx#analyzers-at-query-time) to learn about the different behaviors. + + + + + +## Setting analyzer for index-field + +* To explicitly set an analyzer that will process/tokenize the content of a specific index-field, + set the `analyze()` method within the index definition for that field. + +* Either: + * Specify an analyzer from the [Analyzers available in RavenDB](../indexes/using-analyzers.mdx#analyzers-available-in-ravendb), + * Or specify your own custom analyzer (see [Creating custom analyzers](../indexes/using-analyzers.mdx#creating-custom-analyzers)). + +* If you want RavenDB to use the default analyzers, see [RavenDB's default analyzers](../indexes/using-analyzers.mdx#ravendb). + +* An analyzer may also be set from the Edit Index view in the Studio, see [Index field options](../studio/database/indexes/create-map-index.mdx#index-field-options). + + + + +{`class BlogPosts_ByTagsAndContent extends AbstractIndexCreationTask { + constructor() { + super(); + + this.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content + })\`; + + // Field 'tags' will be tokenized by Lucene's SimpleAnalyzer + this.analyze("tags", "SimpleAnalyzer"); + + // Field 'content' will be tokenized by the Custom analyzer SnowballAnalyzer + this.analyze("content", "Raven.Sample.SnowballAnalyzer"); + } +} +`} + + + + +{`const builder = new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent"); +builder.map = \`docs.Posts.Select(post => new { + tags = post.tags, + content = post.content +})\`; +builder.analyzersStrings["tags"] = "SimpleAnalyzer"; +builder.analyzersStrings["content"] = "Raven.Sample.SnowballAnalyzer"; + +await store.maintenance + .send(new PutIndexesOperation( + builder.toIndexDefinition(store.conventions))); +`} + + + + + + +## RavenDB's default analyzers + +* When no specific analyzer is explicitly assigned to an index-field in the index definition, + RavenDB will use the Default Analyzers to process and tokenize the content of the field, + depending on the specified Indexing Behavior. + +* The **Default Analyzers** are: + * `RavenStandardAnalyzer` - Serves as the [Default Search Analyzer](../indexes/using-analyzers.mdx#using-the-default-search-analyzer). + * `KeywordAnalyzer` - Servers as the [Default Exact Analyzer](../indexes/using-analyzers.mdx#using-the-default-exact-analyzer). + * `LowerCaseKeywordAnalyzer`- Serves as the [Default Analyzer](../indexes/using-analyzers.mdx#using-the-default-analyzer). + +* The available **Indexing Behavior** values are: + * `Exact` + * `Search` + * `No` - This behavior [disables field indexing](../indexes/using-analyzers.mdx#disabling-indexing-for-index-field). + +* See the detailed explanation for each scenario below: + + +##### Using the Default Search Analyzer +* When the indexing behavior is set to `Search` and no analyzer is specified for the index-field, + RavenDB will use the Default Search Analyzer. + By default, this analyzer is the `RavenStandardAnalyzer` (inherits from Lucene's _StandardAnalyzer_). + +* To customize a different analyzer that will serve as your Default Search Analyzer, + set the [Indexing.Analyzers.Search.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzerssearchdefault) configuration key. + +* Using a search analyzer enables full-text search queries against the field. + Given the same sample text from above, _RavenStandardAnalyzer_ will produce the following tokens: + `[quick] [brown] [fox] [jumped] [over] [lazy] [dogs] [bob@hotmail.com] [123432]` + + + +{`class BlogPosts_ByContent extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Search' on index-field 'content' + this.index("content", "Search"); + + // => Index-field 'content' will be processed by the "Default Search Analyzer" + // since no other analyzer is set. + \} +\} +`} + + + + + + +##### Using the Default Exact Analyzer +* When the indexing behavior is set to `Exact`, RavenDB will use the Default Exact Analyzer. + By default, this analyzer is the `KeywordAnalyzer`. + +* _KeywordAnalyzer_ treats the entire content of the index-field as a single token, + preserving the original text's case and ensuring no transformations, such as case normalization or stemming, are applied. + The field's value is indexed exactly as provided, enabling precise, case-sensitive matching at query time. + +* To customize a different analyzer that will serve as your Default Exact Analyzer, + set the [Indexing.Analyzers.Exact.Default ](../server/configuration/indexing-configuration.mdx#indexinganalyzersexactdefault) configuration key. + +* Given the same sample text from above, _KeywordAnalyzer_ will produce a single token: + `[The quick brown fox jumped over the lazy dogs, Bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FirstName = employee.FirstName " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'Exact' on index-field 'FirstName' + this.index("FirstName", "Exact"); + + // => Index-field 'FirstName' will be processed by the "Default Exact Analyzer" + \} +\} +`} + + + + + + +##### Using the Default Analyzer +* When no indexing behavior is set and no analyzer is specified for the index-field, + RavenDB will use the Default Analyzer. + By default, this analyzer is the `LowerCaseKeywordAnalyzer`. + +* _LowerCaseKeywordAnalyzer_ behaves like Lucene's _KeywordAnalyzer_, but additionally performs case normalization, converting all characters to lowercase. + The entire content of the field is processed into a single, lowercased token. + +* To customize a different analyzer that will serve as your Default Analyzer, + set the [Indexing.Analyzers.Default](../server/configuration/indexing-configuration.mdx#indexinganalyzersdefault) configuration key. + +* Given the same sample text from above, _LowerCaseKeywordAnalyzer_ will produce a single token: + `[the quick brown fox jumped over the lazy dogs, bob@hotmail.com 123432.]` + + + +{`class Employees_ByFirstName extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName" + + "\})"; + + // Index-field 'LastName' will be processed by the "Default Analyzer" + // since: + // * No analyzer was specified + // * No Indexing Behavior was specified (neither Exact nor Search) + \} +\} +`} + + + + + + +## Disabling indexing for index-field + +* Use the `No` indexing behavior option to disable indexing of a particular index-field. + In this case: + * No analyzer will process the field, and no terms will be generated from its content. + * The field will not be available for querying. + * The field will still be accessible for extraction when [projecting query results](../indexes/querying/projections.mdx). + +* This is useful when you need to [store the field data in the index](../indexes/storing-data-in-index.mdx) and only intend to use it for query projections. + + + +{`class BlogPosts_ByTitle extends AbstractIndexCreationTask \{ + constructor() \{ + super(); + + this.map = "docs.Posts.Select(post => new \{ " + + " tags = post.tags, " + + " content = post.content " + + "\})"; + + // Set the Indexing Behavior: + // ========================== + + // Set 'No' on index-field 'content' + this.index("content", "No"); + + // Set 'Yes' to store the original content of field 'content' in the index + this.store("content", "Yes"); + + // => No analyzer will process field 'content', + // it will only be stored in the index. + \} +\} +`} + + + + + +## Creating custom analyzers + +* **Availability & file type**: + The custom analyzer you are referencing must be available to the RavenDB server instance. + You can create and add custom analyzers to RavenDB as `.cs` files. + +* **Scope**: + Custom analyzers can be defined as: + + * **Database Custom Analyzers** - can only be used by indexes of the database where they are defined. + * **Server-Wide Custom Analyzers** - can be used by indexes on all databases across all servers in the cluster. + + A database analyzer may have the same name as a server-wide analyzer. + In this case, the indexes of that database will use the database version of the analyzer. + You can think of database analyzers as overriding server-wide analyzers with the same names. + +* **Ways to create**: + There are three ways to create a custom analyzer and add it to your server: + + 1. [Add custom analyzer via Studio](../indexes/using-analyzers.mdx#add-custom-analyzer-via-studio) + 2. [Add custom analyzer via Client API](../indexes/using-analyzers.mdx#add-custom-analyzer-via-client-api) + 3. [Add custom analyzer directly to RavenDB's binaries](../indexes/using-analyzers.mdx#add-custom-analyzer-directly-to-ravendbs-binaries) + + +##### Add custom analyzer via Studio + +Custom analyzers can be added from the Custom Analyzers view in the Studio. +Learn more in this [Custom analyzers](../studio/database/settings/custom-analyzers.mdx) article. + + + + +##### Add custom analyzer via Client API + +First, create a class that inherits from the abstract `Lucene.Net.Analysis.Analyzer` class. +(you need to reference `Lucene.Net.dll`, which is included with the RavenDB Server package). +For example: + + + +{`public class MyAnalyzer : Lucene.Net.Analysis.Analyzer +\{ + public override TokenStream TokenStream(string fieldName, TextReader reader) + \{ + // Implement your analyzer's logic + throw new CodeOmitted(); + \} +\} +`} + + + +Next, use `PutAnalyzersOperation` to deploy the analyzer to a specific database. +By default, `PutAnalyzersOperation` will apply to the [default database](../client-api/setting-up-default-database.mdx) of the document store you're using. +To target a different database, use the [forDatabase()](../client-api/operations/how-to/switch-operations-to-a-different-database.mdx) method. + +To make it a server-wide analyzer, use the `PutServerWideOperation` operation.` + + + +{`await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`await store.maintenance.send(new PutServerWideAnalyzersOperation(analyzerDefinition)); +`} + + + + +{`const analyzerDefinition = \{ + name: "analyzerName", + code: "code" +\}; +`} + + + +| Parameter | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | The class name of your custom analyzer, as defined in your code. | +| **code** | `string` | Compilable csharp code:
A class that inherits from `Lucene.Net.Analysis.Analyzer`,
including the containing namespace and the necessary `using` statements. | + +**Client API example**: + + + +{`const analyzerDefinition = \{ + name: "MyAnalyzer", + code: "using System.IO;\\n" + + "using Lucene.Net.Analysis;\\n" + + "using Lucene.Net.Analysis.Standard;\\n" + + "\\n" + + "namespace MyAnalyzer\\n" + + "\{\\n" + + " public class MyAnalyzer : Lucene.Net.Analysis.Analyzer\\n" + + " \{\\n" + + " public override TokenStream TokenStream(string fieldName, TextReader reader)\\n" + + " \{\\n" + + " throw new CodeOmitted();\\n" + + " \}\\n" + + " \}\\n" + + "\}\\n" +\}; + +await store.maintenance.send(new PutAnalyzersOperation(analyzerDefinition)) +`} + + + + + + +##### Add custom analyzer directly to RavenDB's binaries + +Another way to add custom analyzers to RavenDB is by placing them next to RavenDB's binaries. + +The fully qualified name must be specified for any index-field that will be tokenized by the analyzer. + +Note that the analyzer must be compatible with .NET Core 2.0 (e.g., a .NET Standard 2.0 assembly). + +This is the only method for adding custom analyzers in RavenDB versions older than 5.2. + + + + +## Viewing the indexed terms + +The terms generated for each index-field can be viewed in the Studio. + +![The index terms](../assets/index-terms-1.png) + +1. These are the index-fields +2. Click the "Terms" button to view the generated terms for each field + +---- + +![The index terms](../assets/index-terms-2.png) + +1. This is the "index-field name". +2. These are the terms generated for the index-field. + In this example the `StopAnalyzer` was used to tokenize the text. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-csharp.mdx new file mode 100644 index 0000000000..8484315d55 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-csharp.mdx @@ -0,0 +1,550 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public Dictionary Attributes \{ get; set; \} +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey : AbstractIndexCreationTask +{ + public Products_ByAttributeKey() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate dynamic-index-fields from the Attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be item.Key + // The actual field terms will be derived from item.Value + _ = p.Attributes.Select(item => CreateField(item.Key, item.Value)) + }; + } +} +`} + + + + +{`public class Products_ByAttributeKey_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAttributeKey_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p.Attributes).map(key => createField(key, p.Attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + })" + }; + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + The `_` property is Not queryable but used only in the index definition syntax. + * To get all documents with some 'Size' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + .WhereEquals("Size", 42) + .ToList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public string FirstName \{ get; set; \} + public string LastName \{ get; set; \} + public string Title \{ get; set; \} + // ... +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByAnyField_JS() + { + // This will index EVERY FIELD under the top level of the document + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'LastName' is a dynamic-index-field that was indexed from the document + .WhereEquals("LastName", "Doe") + .ToList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + + // The VALUE of ProductType will be dynamically indexed + public string ProductType \{ get; set; \} + public int PricePerUnit \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType : AbstractIndexCreationTask +{ + public Products_ByProductType() + { + Map = products => from p in products + select new + { + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + _ = CreateField(p.ProductType, p.PricePerUnit) + }; + } +} +`} + + + + +{`public class Products_ByProductType_JS : AbstractJavaScriptIndexCreationTask +{ + public Products_ByProductType_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' + .WhereEquals("Electronics", 23) + .ToList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product +\{ + public string Id \{ get; set; \} + public string Name \{ get; set; \} + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public List Attributes \{ get; set; \} +\} + +public class Attribute +\{ + public string PropName \{ get; set; \} + public string PropValue \{ get; set; \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName : AbstractIndexCreationTask +{ + public Attributes_ByName() + { + Map = products => from a in products + select new + { + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + _ = a.Attributes.Select(item => CreateField(item.PropName, item.PropValue)), + + // A regular index field can be defined as well: + Name = a.Name + }; + } +} +`} + + + + +{`public class Attributes_ByName_JS : AbstractJavaScriptIndexCreationTask +{ + public Attributes_ByName_JS() + { + Maps = new HashSet + { + @"map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + }; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`IList matchingDocuments = session + .Advanced + .DocumentQuery() + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + .WhereEquals("Width", 10) + .ToList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) diff --git a/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-java.mdx b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-java.mdx new file mode 100644 index 0000000000..0fd89b32ac --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-java.mdx @@ -0,0 +1,480 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + private Dictionary attributes; + + // get + set implementation ... +\} +`} + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +* **The index**: + The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAttributeKey_JS() { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " + + " { indexing: 'Search', storage: false, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + * To get all documents with some 'size' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAttributeKey_JS.class) + .whereEquals("size", 42) + .toList(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey/JS' where size = 42 +`} + + + + +## Example - index any field + + + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`public class Product \{ + private String id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + private String firstName; + private String lastName; + private String title; + // ... + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`public class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + public Products_ByAnyField_JS() { + + // This will index EVERY FIELD under the top level of the document + setMaps(Sets.newHashSet( + "map('Products', function (p) { " + + " return { " + + " _: Object.keys(p).map(key => createField(key, p[key], " + + " { indexing: 'Search', storage: true, termVector: null })) " + + " }; " + + "}) " + )); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'lastName' use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByAnyField_JS.class) + .whereEquals("lastName", "Doe") + .toList(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. + + + +* **The document**: + + +{`public class Product \{ + private String id; + + // The VALUE of productType will be dynamically indexed + private String productType; + private int pricePerUnit; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +* **The index**: + The following index will index the **value** of document field 'productType'. + + This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`public class Products_ByProductType extends AbstractIndexCreationTask { + public Products_ByProductType() { + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`List matchingDocuments = session + .query(Product.class, Products_ByProductType.class) + .whereEquals("Electronics", 23) + .toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`public class Product \{ + private String id; + private String name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + private List attributes; + + // get + set implementation ... +\} + +public class Attribute \{ + private String propName; + private String propValue; + + // get + set implementation ... +\} +`} + + + + + +{`// Sample document content +\{ +name": "SomeName", +attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's propName **value**. + E.g., 'propName' value `Width` will be a dynamic-index-field. + + + + +{`public class Attributes_ByName extends AbstractIndexCreationTask { + public Attributes_ByName() { + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +* **The query**: + * To get all documents matching a specific attribute property use: + + + +{`List matchingDocuments = session + .query(Product.class, Attributes_ByName.class) + .whereEquals("Width", 10) + .toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-nodejs.mdx new file mode 100644 index 0000000000..146a2f25c5 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-nodejs.mdx @@ -0,0 +1,556 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + + +#### Example - index any field under object +The following allows you to: + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, attributes) \{ + this.id = id; + + // The KEYS under the attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + this.attributes = attributes; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "attributes": \{ + "color": "Red", + "size": 42 + \} +\} +`} + + + +**The index**: + +* The following index will index any field under the `attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the attribute field **key**. + e.g. Keys `color` & `size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // Call 'createField' to generate dynamic-index-fields from the attributes object keys + // Using '_' is just a convention. Any other string can be used instead of '_' + + // The actual field name will be the key + // The actual field terms will be derived from p.attributes[key] + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], { + indexing: "Search", + storage: false, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* You can now query the generated dynamic-index fields. + Property `_` is Not queryable, it is only used in the index definition syntax. + +* To get all documents with some 'size' use: + + + + +{`const matchingDocuments = session.query({indexName: 'Products_ByAttributeKey'}) + // 'size' is a dynamic-index-field that was indexed from the attributes object + .whereEquals('size', 42) + .all(); +`} + + + + +{`// 'size' is a dynamic-index-field that was indexed from the attributes object +from index 'Products/ByAttributeKey' where size = 42 +`} + + + + + + + +#### Example - index any field +The following allows you to: + +* Define an index on a collection **without** needing any common structure between the indexed documents. +* After index is deployed, any new field added to the document will be indexed as well. + + + +Consider if that is a true necessity, as indexing every single field can end up costing time and disk space. + + +**The document**: + + +{`class Product \{ + constructor(id, firstName, lastName, title) \{ + this.id = id; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + this.firstName = firstName; + this.lastName = lastName; + this.title = title; + // ... + \} +\} +`} + + + + + +{`// Sample document content +\{ + "firstName": "John", + "lastName": "Doe", + "title": "Engineer", + // ... +\} +`} + + + +**The index**: + +* The following index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the field **key**. + e.g. Keys `firstName` & `lastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // This will index EVERY FIELD under the top level of the document + _: Object.keys(p).map(key => createField(key, p[key], { + indexing: "Search", + storage: true, + termVector: null + })) + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents with some 'lastName' use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByAnyField_JS' }) + // 'lastName' is a dynamic-index-field that was indexed from the document + .whereEquals('lastName', 'Doe') + .all(); +`} + + + + +{`// 'lastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where lastName = "Doe" +`} + + + + + + + + +## Indexing documents fields VALUES + + +#### Example - basic +This example shows: + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. +* For a more practical usage see the [Example](../indexes/using-dynamic-fields.mdx#example---index-a-list-of-properties) below. +**The document**: + + +{`class Product \{ + constructor(id, productType, pricePerUnit) \{ + this.id = id; + + // The VALUE of productType will be dynamically indexed + this.productType = productType; + this.pricePerUnit = pricePerUnit; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "productType": "Electronics", + "pricePerUnit": 23 +\} +`} + + + +**The index**: + +* The following index will index the **value** of document field 'productType'. + +* This value will be the dynamic-index-field name on which you can query. + e.g. Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractCsharpIndexCreationTask { + constructor () { + super(); + + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + this.map = "docs.Products.Select(p => new { " + + " _ = this.CreateField(p.productType, p.pricePerUnit) " + + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + _: [ + // The field name will be the value of document field 'productType' + // The field terms will be derived from document field 'pricePerUnit' + createField(p.productType, p.pricePerUnit, { + indexing: "Search", + storage: false, + termVector: null + }) + ] + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents of some product type having a specific price per unit use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Products_ByProductType' }) + // 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' + .whereEquals('Electronics', 23) + .all(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'productType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + + + + +#### Example - list +The following allows you to: + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. +**The document**: + + +{`class Product \{ + constructor(id, name, attributes) \{ + this.id = id; + this.name = name; + + // For each element in this list, the VALUE of property 'propName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + this.attributes = attributes; + \} +\} + +class Attribute \{ + constructor(propName, propValue) \{ + this.propName = propName; + this.propValue = propValue; + \} +\} +`} + + + + + +{`// Sample document content +\{ + "name": "SomeName", + "attributes": [ + \{ + "propName": "Color", + "propValue": "Blue" + \}, + \{ + "propName": "Width", + "propValue": "10" + \}, + \{ + "propName": "Length", + "propValue": "20" + \}, + ... + ] +\} +`} + + + +**The index**: + +* The following index will create a dynamic-index-field per item in the document's `attributes` list. + New items added to the attributes list after index creation time will be dynamically indexed as well. + +* The actual dynamic-index-field name on which you can query will be the item's propName **value**. + e.g. 'propName' value `Width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractCsharpIndexCreationTask +{ + constructor () { + super(); + + // For each attribute item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + // A regular-index-field (Name) is defined as well + this.map = + "docs.Products.Select(p => new { " + + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " + + " Name = p.name " + + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + const { createField } = this.mapUtils(); + + this.map("Products", p => { + return { + // For each item, the field name will be the value of field 'propName' + // The field terms will be derived from field 'propValue' + _: p.attributes.map(item => createField(item.propName, item.propValue, { + indexing: "Search", + storage: true, + termVector: null + })), + + // A regular-index-field can be defined as well: + Name: p.name + }; + }); + } +} +`} + + + + +**The query**: + +* To get all documents matching a specific attribute property use: + + + + +{`const matchingDocuments = session.query({ indexName: 'Attributes/ByName' }) + // 'Width' is a dynamic-index-field that was indexed from the attributes list + .whereEquals('Width', 10) + .all(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + + +## CreateField syntax + +#### Syntax for LINQ-index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | Name of the dynamic-index-field | +| **fieldValue** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`false` - will set `FieldStorage.No` (default value)
`true` - will set `FieldStorate.Yes` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`null` - `FieldIndexing.Default` (default value)
`false` - `FieldIndexing.Exact`
`true` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-php.mdx b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-php.mdx new file mode 100644 index 0000000000..690dfe4bd2 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-php.mdx @@ -0,0 +1,560 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`use Ds\\Map as DSMap; + +class Product +\{ + private ?string $id = null; + + // The KEYS under the Attributes object will be dynamically indexed + // Fields added to this object after index creation time will also get indexed + public ?DSMap $attributes = null; +\} +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from p in docs.Products select new {" . + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" . + "}"; + } +} +`} + + + + +{`class Products_ByAttributeKey_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { " . + " return { " . + " _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], " . + " { indexing: 'Search', storage: false, termVector: null })) " . + " }; " . + "}) " + ]); + } +} +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAttributeKey::class) + // 'Size' is a dynamic-index-field that was indexed from the Attributes object + ->whereEquals("Size", 42) + ->toList(); +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product +\{ + private ?string $id = null; + + // All KEYS in the document will be dynamically indexed + // Fields added to the document after index creation time will also get indexed + public ?string $firstName = null; + public ?string $lastName = null; + public ?string $title = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // This will index EVERY FIELD under the top level of the document + $this->setMaps([ + "map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByAnyField_JS::class) + // 'LastName' is a dynamic-index-field that was indexed from the document + ->whereEquals("LastName", "Doe") + ->toList(); +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + + // The VALUE of ProductType will be dynamically indexed + public ?string $productType = null; + public ?int $pricePerUnit = null; + + // ... getters and setters +\} +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Call 'CreateField' to generate the dynamic-index-fields + // The field name will be the value of document field 'ProductType' + // The field terms will be derived from document field 'PricePerUnit' + $this->map = "docs.Products.Select(p => new { " . + " _ = this.CreateField(p.productType, p.pricePerUnit) " . + "})"; + } +} +`} + + + + +{`class Products_ByProductType_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: createField(p.ProductType, p.PricePerUnit, + { indexing: 'Search', storage: true, termVector: null }) + }; + })" + ]); + } +} +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Products_ByProductType::class) +// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +->whereEquals("Electronics", 23) +->toList(); +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Product +\{ + public ?string $id = null; + public ?string $name = null; + + // For each element in this list, the VALUE of property 'PropName' will be dynamically indexed + // e.g. Color, Width, Length (in ex. below) will become dynamic-index-fields + public ?AttributeList $attributes = null; + + // ... getters and setters +\} + +class Attribute +\{ + public ?string $propName = null; + public ?string $propValue = null; + + // ... getters and setters +\} + +class AttributeList extends TypedList +\{ + protected function __construct() + \{ + parent::__construct(Attribute::class); + \} +\} +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // Define the dynamic-index-fields by calling CreateField + // A dynamic-index-field will be generated for each item in the Attributes list + + // For each item, the field name will be the value of field 'PropName' + // The field terms will be derived from field 'PropValue' + + $this->map = + "docs.Products.Select(p => new { " . + " _ = p.attributes.Select(item => this.CreateField(item.propName, item.propValue)), " . + " Name = p.name " . + "})"; + } +} +`} + + + + +{`class Attributes_ByName_JS extends AbstractJavaScriptIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->setMaps([ + "map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + })" + ]); + } +} +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`/** @var array $matchingDocuments */ +$matchingDocuments = $session + ->advanced() + ->documentQuery(Product::class, Attributes_ByName::class) + // 'Width' is a dynamic-index-field that was indexed from the Attributes list + ->whereEquals("Width", 10) + ->toList(); +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing` | | +| **TermVector** | `FieldTermVector` | | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-python.mdx b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-python.mdx new file mode 100644 index 0000000000..274c90ba20 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-dynamic-fields-python.mdx @@ -0,0 +1,512 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* In RavenDB different documents can have different shapes. + Documents are schemaless - new fields can be added or removed as needed. + +* For such dynamic data, you can define indexes with **dynamic-index-fields**. + +* This allows querying the index on fields that aren't yet known at index creation time, + which is very useful when working on highly dynamic systems. + +* Any value type can be indexed, string, number, date, etc. + +* An index definition can contain both dynamic-index-fields and regular-index-fields. + +* In this page: + + * [Indexing documents fields KEYS](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-keys) + * [Example - index any field under object](../indexes/using-dynamic-fields.mdx#example---index-any-field-under-object) + * [Example - index any field](../indexes/using-dynamic-fields.mdx#example---index-any-field) + * [Indexing documents fields VALUES](../indexes/using-dynamic-fields.mdx#indexing-documents-fields-values) + * [Example - basic](../indexes/using-dynamic-fields.mdx#example---basic) + * [Example - list](../indexes/using-dynamic-fields.mdx#example---list) + * [CreateField syntax](../indexes/using-dynamic-fields.mdx#createfield-syntax) + * [Indexed fields & terms view](../indexes/using-dynamic-fields.mdx#indexed-fields--terms-view) + + + +## Indexing documents fields KEYS + +## Example - index any field under object + + + +* Index any field that is under the some object from the document. +* After index is deployed, any new field added to the this object will be indexed as well. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, attributes: Dict[str, object] = None): + self.Id = Id + + # The KEYS under the Attributes object will be dynamically indexed + # Fields added to this object after index creation time will also get indexed + self.attributes = attributes +`} + + + + +{`// Sample document content +\{ + "Attributes": \{ + "Color": "Red", + "Size": 42 + \} +\} +`} + + + +* **The index**: + The below index will index any field under the `Attributes` object from the document, + a dynamic-index-field will be created for each such field. + New fields added to the object after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the attribute field **key**. + E.g., Keys `Color` & `Size` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAttributeKey(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from p in docs.Products select new {" + "_ = p.attributes.Select(item => CreateField(item.Key, item.Value))" + "}" + ) +`} + + + + +{`class Products_ByAttributeKey_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p.attributes).map(key => createField(key, p.attributes[key], + { indexing: 'Search', storage: true, termVector: null })) + }; + }) + """ + } +`} + + + + + +* **The query**: + * You can now query the generated dynamic-index fields. + * To get all documents with some 'size' use: + + + +{`matching_documents = list( + session.query_index_type(Products_ByAttributeKey, Product) + # 'size' is a dynamic-index-field that was indexed from the attributes object + .where_equals("size", 42) +) +`} + + + + +{`// 'Size' is a dynamic-index-field that was indexed from the Attributes object +from index 'Products/ByAttributeKey' where Size = 42 +`} + + + + +## Example - index any field + + + + * Define an index on a collection **without** needing any common structure between the indexed documents. + * After index is deployed, any new field added to the document will be indexed as well. + + + + +Consider whether this is really necessary, as indexing every single field can end up costing time and disk space. + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, first_name: str = None, last_name: str = None, title: str = None): + self.Id = Id + + # All KEYS in the document will be dynamically indexes + # Fields added to the document after index creation time wil also get indexed + self.first_name = first_name + self.last_name = last_name + self.title = title + # ... +`} + + + + + +{`// Sample document content + \{ + "FirstName": "John", + "LastName": "Doe", + "Title": "Engineer", + // ... +\} +`} + + + +* **The index**: + The below index will index any field from the document, + a dynamic-index-field will be created for each field. + New fields added to the document after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the field **key**. + E.g., Keys `FirstName` & `LastName` will become the actual dynamic-index-fields. + + + + +{`class Products_ByAnyField_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + # This will index EVERY FIELD under the top level of the document + self.maps = { + """ + map('Products', function (p) { + return { + _: Object.keys(p).map(key => createField(key, p[key], + { indexing: 'Search', storage: true, termVector: null })) + } + }) + """ + } +`} + + + + +* **The query**: + * To get all documents with some 'LastName' use: + + + +{`# 'last_name' is a dynamic-index-field that was indexed from the document +matching_documents = list( + session.query_index_type(Products_ByAnyField_JS, Product).where_equals("last_name", "Doe") +) +`} + + + + +{`// 'LastName' is a dynamic-index-field that was indexed from the document +from index 'Products/ByAnyField/JS' where LastName = "Doe" +`} + + + + + + +## Indexing documents fields VALUES + +## Example - basic + + + +* Only the **basic concept** of creating a dynamic-index-field from the **value** of a document field. +* Documents can then be queried based on those indexed values. + + + +* **The document**: + + +{`class Product: + def __init__(self, Id: str = None, product_type: str = None, price_per_unit: float = None): + self.Id = Id + + # The VALUE of ProductType will be dynamically indexed + self.product_type = product_type + self.price_per_unit = price_per_unit +`} + + + + + +{`// Sample document content +\{ + "ProductType": "Electronics", + "PricePerUnit": 23 +\} +`} + + + +* **The index**: + The below index will index the **value** of document field 'ProductType'. + + This value will be the dynamic-index-field name on which you can query. + E.g., Field value `Electronics` will be the dynamic-index-field. + + + + +{`class Products_ByProductType(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + # Call 'CreateField' to generate the dynamic-index-fields + # The field name will be the value of document field 'product_type' + # The field terms will be derived from document field 'price_per_unit' + self.map = "from p in docs.Products select new { _ = CreateField(p.product_type, p.price_per_unit)}" +`} + + + + +{`class Products_ByProductType_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: createField(p.product_type, p.price_per_unit, + { indexing: 'Search', storage: true, termVector: null }) + }; + }) + """ + } +`} + + + + +* **The query**: + * To get all documents of some product type having a specific price per unit use: + + + +{`# 'electronics' is the dynamic-index-field that was indexed from the document 'product_type' +matching_documents = list( + session.advanced.document_query_from_index_type(Products_ByProductType, Product).where_equals( + "electronics", 23 + ) +) +`} + + + + +{`// 'Electronics' is the dynamic-index-field that was indexed from document field 'ProductType' +from index 'Products/ByProductType' where Electronics = 23 +`} + + + + +## Example - list + + + +* Index **values** from items in a list +* After index is deployed, any item added this list in the document will be dynamically indexed as well. + + + +* **The document**: + + +{`class Attribute: + def __init__(self, prop_name: str = None, prop_value: str = None): + self.prop_name = prop_name + self.prop_value = prop_value + + +class Product: + def __init__(self, Id: str = None, name: str = None, attributes: List[Attribute] = None): + self.Id = Id + self.name = name + # For each element in this list, the VALUE of property 'prop_name' will be dynamically indexed + # e.g. color, width, length (in ex. below) will become dynamic-index-field + self.attributes = attributes +`} + + + + + +{`// Sample document content +\{ +Name": "SomeName", +Attributes": [ + \{ + "PropName": "Color", + "PropValue": "Blue" + \}, + \{ + "PropName": "Width", + "PropValue": "10" + \}, + \{ + "PropName": "Length", + "PropValue": "20" + \}, + ... + +\} +`} + + + +* **The index**: + The below index will create a dynamic-index-field per item in the document's `Attributes` list. + New items added to the Attributes list after index creation time will be dynamically indexed as well. + + The actual dynamic-index-field name on which you can query will be the item's PropName **value**. + E.g., 'PropName' value `width` will be a dynamic-index-field. + + + + +{`class Attributes_ByName(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = ( + "from a in docs.Products select new " + "{ _ = a.attributes.Select( item => CreateField(item.prop_name, item.prop_value)), name = a.name " + "}" + ) +`} + + + + +{`class Attributes_ByName_JS(AbstractJavaScriptIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + map('Products', function (p) { + return { + _: p.Attributes.map(item => createField(item.PropName, item.PropValue, + { indexing: 'Search', storage: true, termVector: null })), + Name: p.Name + }; + }) + """ + } +`} + + + + +* **The query**: + To get all documents matching a specific attribute property use: + + + +{`matching_documents = list( + session.advanced.document_query_from_index_type(Attributes_ByName, Product).where_equals( + "width", 10 + ) +) +`} + + + + +{`// 'Width' is a dynamic-index-field that was indexed from the Attributes list +from index 'Attributes/ByName' where Width = 10 +`} + + + + + + +## CreateField syntax + +#### Syntax for Index: + + + +{`object CreateField(string name, object value); + +object CreateField(string name, object value, bool stored, bool analyzed); + +object CreateField(string name, object value, CreateFieldOptions options); +`} + + + +#### Syntax for JavaScript-index: + + + +{`createField(fieldName, fieldValue, options); // returns object +`} + + + +| Parameters | Type | Description | +|------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | `string` | Name of the dynamic-index-field | +| **value** | `object` | Value of the dynamic-index-field
The field Terms are derived from this value. | +| **stored** | `bool` | Sets [FieldStorage](../indexes/storing-data-in-index.mdx)

`False` - will set `FieldStorage.NO` (default value)
`True` - will set `FieldStorate.YES` | +| **analyzed** | `bool` | Sets [FieldIndexing](../indexes/using-analyzers.mdx)

`None` - `FieldIndexing.Default` (default value)
`False` - `FieldIndexing.Exact`
`True` - `FieldIndexing.Search` | +| **options** | `CreateFieldOptions` | Dynamic-index-field options | + +| CreateFieldOptions | | | +|--------------------|--------------------|----------------------------------------------------------------------------| +| **Storage** | `FieldStorage?` | Learn about [storing data](../indexes/storing-data-in-index.mdx) in the index. | +| **Indexing** | `FieldIndexing?` | Learn about [using analyzers](../indexes/using-analyzers.mdx) in the index. | +| **TermVector** | `FieldTermVector?` | Learn about [term vectors](../indexes/using-term-vectors.mdx) in the index. | + + + +* All above examples have used the character `_` in the dynamic-index-field definition. + However, using `_` is just a convention. Any other string can be used instead. + +* This property is Not queryable, it is only used in the index definition syntax. + The actual dynamic-index-fields that are generated are defined by the `CreateField` method. + + + + + +## Indexed fields & terms view + +The generated dynamic-index-fields and their indexed terms can be viewed in the **Terms View**. +Below are sample index fields & their terms generated from the last example. + +![Figure 1. Go to terms view](../assets/dynamic-index-fields-1.png) + +![Figure 2. Indexed fields & terms](../assets/dynamic-index-fields-2.png) + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_using-term-vectors-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_using-term-vectors-csharp.mdx new file mode 100644 index 0000000000..7da57d0a06 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_using-term-vectors-csharp.mdx @@ -0,0 +1,145 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A [Term Vector](https://en.wikipedia.org/wiki/Vector_space_model) is a representation of a text document + as a vector of identifiers. + Lucene indexes can contain term vectors for documents they index. +* Term vectors can be used for various purposes, including similarity searches, information filtering + and retrieval, and indexing. + A book's index, for example, may have term vector enabled on the book's **subject** field, to be able + to use this field to search for books with similar subjects. +* RavenDB features like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) leverage + stored term vectors to accomplish their goals. + +* In this page: + * [Creating an index and enabling Term Vectors on a field](../indexes/using-term-vectors.mdx#creating-an-index-and-enabling-term-vectors-on-a-field) + * [Using the API](../indexes/using-term-vectors.mdx#using-the-api) + * [Using Studio](../indexes/using-term-vectors.mdx#using-studio) + + +## Creating an index and enabling Term Vectors on a field + +Indexes that include term vectors can be created and configured using the API +or Studio. + +## Using the API + +To create an index and enable Term Vectors on a specific field, we can - + +A. Create an index using the `AbstractIndexCreationTask`, and specify the term vectors there. +B. Or, we can define our term vectors in the `IndexDefinition` (directly or using the `IndexDefinitionBuilder`). + + + + +{`public class BlogPosts_ByTagsAndContent : AbstractIndexCreationTask +{ + public BlogPosts_ByTagsAndContent() + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }; + + Indexes.Add(x => x.Content, FieldIndexing.Search); + TermVectors.Add(x => x.Content, FieldTermVector.WithPositionsAndOffsets); + } +} +`} + + + + +{`IndexDefinitionBuilder indexDefinitionBuilder = + new IndexDefinitionBuilder("BlogPosts/ByTagsAndContent") + { + Map = users => from doc in users + select new + { + doc.Tags, + doc.Content + }, + Indexes = + { + { x => x.Content, FieldIndexing.Search } + }, + TermVectors = + { + { x => x.Content, FieldTermVector.WithPositionsAndOffsets } + } + }; + +IndexDefinition indexDefinition = indexDefinitionBuilder + .ToIndexDefinition(store.Conventions); + +store.Maintenance.Send(new PutIndexesOperation(indexDefinition)); +`} + + + + +Available Term Vector options include: + + + +{`public enum FieldTermVector +\{ + /// + /// Do not store term vectors + /// + No, + + /// + /// Store the term vectors of each document. A term vector is a list of the document's + /// terms and their number of occurrences in that document. + /// + Yes, + + /// + /// Store the term vector + token position information + /// + WithPositions, + + /// + /// Store the term vector + Token offset information + /// + WithOffsets, + + /// + /// Store the term vector + Token position and offset information + /// + WithPositionsAndOffsets +\} +`} + + + +Learn which Lucene API methods and constants are available [here](https://lucene.apache.org/core/3_6_2/api/all/org/apache/lucene/document/Field.TermVector.html). + +## Using Studio + +Let's use as an example one of Studio's sample indexes, `Product/Search`, that has term vector +enabled on its `Name` field so a feature like [MoreLikeThis](../client-api/session/querying/how-to-use-morelikethis.mdx) +can use this fiels to select a product and find products similar to it. + +![Term vector enabled on index field](../assets/term-vector-enabled.png) + +We can now use a query like: + + + +{`from index 'Product/Search' +where morelikethis(id() = 'products/7-A') +`} + + + + + + diff --git a/versioned_docs/version-7.1/indexes/_using-term-vectors-java.mdx b/versioned_docs/version-7.1/indexes/content/_using-term-vectors-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_using-term-vectors-java.mdx rename to versioned_docs/version-7.1/indexes/content/_using-term-vectors-java.mdx diff --git a/versioned_docs/version-7.1/indexes/_using-term-vectors-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_using-term-vectors-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/_using-term-vectors-nodejs.mdx rename to versioned_docs/version-7.1/indexes/content/_using-term-vectors-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/content/_what-are-indexes-csharp.mdx b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-csharp.mdx new file mode 100644 index 0000000000..947039be10 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-csharp.mdx @@ -0,0 +1,235 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public class Employees_ByNameAndCountry : AbstractIndexCreationTask +\{ + public class IndexEntry + \{ + // The index-fields + public string LastName \{ get; set; \} + public string FullName \{ get; set; \} + public string Country \{ get; set; \} + \} + + public Employees_ByNameAndCountry() + \{ + Map = employees => from employee in employees + select new IndexEntry() + \{ + // Define the content for each index-field + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.Country + \}; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `Execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().Execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +IList employeesFromUK = session + .Query() + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .Where(x => x.LastName == "King" && x.Country == "UK") + .OfType() + .ToList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_what-are-indexes-java.mdx b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-java.mdx new file mode 100644 index 0000000000..8c5adfb5e7 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-java.mdx @@ -0,0 +1,222 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending the `AbstractIndexCreationTask` class. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#using-abstractindexcreationtask). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask \{ + public Employees_ByNameAndCountry() \{ + map = "docs.Employees.Select(employee => new \{ " + + " LastName = employee.LastName, " + + " FullName = (employee.FirstName + \\" \\") + employee.LastName, " + + " Country = employee.Address.Country " + + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +new Employees_ByNameAndCountry().execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +List employeesFromUK = session + .query(Employee.class, Employees_ByNameAndCountry.class) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_what-are-indexes-nodejs.mdx b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-nodejs.mdx new file mode 100644 index 0000000000..84784104b4 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-nodejs.mdx @@ -0,0 +1,229 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by extending `AbstractJavaScriptIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`// Define the index: +// ================= + +class Employees_ByNameAndCountry extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Employees", employee => \{ + return \{ + // Define the content for each index-field: + // ======================================== + LastName: employee.LastName, + FullName: employee.FirstName + " " + employee.LastName, + Country: employee.Address.Country + \}; + \}); + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// Deploy the index to the server: +// =============================== + +const employeesIndex = new Employees_ByNameAndCountry(); +await employeesIndex.execute(store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`// Query the database using the index: +// =================================== + +const employeesFromUK = await session + .query(\{ indexName: employeesIndex.getIndexName() \}) + // Here we query for all Employee documents that are from the UK + // and have 'King' in their LastName field: + .whereEquals("LastName", "King") + .whereEquals("Country", "UK") + .all(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_what-are-indexes-php.mdx b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-php.mdx new file mode 100644 index 0000000000..b88f6ee9cd --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-php.mdx @@ -0,0 +1,214 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`class Employees_ByFirstAndLastName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + $this->map = "docs.Employees.Select(employee => new \{" . + " FirstName = employee.FirstName," . + " LastName = employee.LastName" . + "\})"; + \} +\} +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`// save index on server +(new Employees_ByFirstAndLastName())->execute($store); +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`/** @var array $results */ +$results = $session->query(Employee::class, Employees_ByFirstAndLastName::class) + ->whereEquals('FirstName', "Robert") + ->toList(); +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.1/indexes/content/_what-are-indexes-python.mdx b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-python.mdx new file mode 100644 index 0000000000..ff56895d0e --- /dev/null +++ b/versioned_docs/version-7.1/indexes/content/_what-are-indexes-python.mdx @@ -0,0 +1,225 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Indexes in RavenDB enable efficient querying by processing raw data and providing fast query results without scanning the entire dataset each and every time. + Learn more in the [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) below. + +* This page provides a [Basic example](../indexes/what-are-indexes.mdx#basic-example) of creating, deploying, and querying an index. + Additional examples can be found in [Creating and deploying indexes](../indexes/creating-and-deploying.mdx), [Map Indexes](../indexes/map-indexes.mdx), + and many other articles under the "Indexes" menu. + +* In this page: + * [Indexes overview](../indexes/what-are-indexes.mdx#indexes-overview) + * [Types of indexes](../indexes/what-are-indexes.mdx#types-of-indexes) + * [Basic example](../indexes/what-are-indexes.mdx#basic-example) + * [Understanding index query results](../indexes/what-are-indexes.mdx#understanding-index-query-results) + * [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources) + + + +## Indexes overview + +**Indexes are fundamental**: + +* Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results. +* ALL queries in RavenDB use an index to deliver results and ensure optimal performance. + Learn more in [Queries always provide results using an index](../client-api/session/querying/how-to-query.mdx#queries-always-provide-results-using-an-index). +**Main concepts**: + +* When discussing indexes in RavenDB, three key components come into play: + * The index definition + * The indexing process + * The indexed data + +* Each of these components is described in detail in [Indexes - The moving parts](../studio/database/indexes/indexes-overview.mdx#indexes---the-moving-parts). +**The indexing process**: + +* The indexing process iterates over the raw documents, creating an **index-entry** for each document that is processed. + (Usually a single index-entry is created per raw document, unless working with a [fanout index](../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document)). +* Each index-entry contains **index-fields**, and each index-field contains content (**index-terms**) that was generated from the raw documents, + as defined by the index definition and depending on the [analyzer](../indexes/using-analyzers.mdx) used. +* A map is built between the indexed-terms and the documents they originated from, + enabling you to query for documents based on the indexed data. +**Automatic data processing**: + +* Once defined and deployed, an index will initially process the entire dataset. + After that, the index will only process documents that were modified, added or deleted. + This happens automatically without requiring direct user intervention. +* For example, if changes are made to documents in the "Orders" collection, + all indexes defined for the "Orders" collection will be triggered to update the index with the new data. +* This approach helps avoid costly table scans, allows the server to respond quickly, + and reduces the load on queries while optimizing machine resource usage. +**Background operation**: + +* RavenDB indexes are designed to run asynchronously in the background. +* The indexing process does not block or interrupt database operations, such as writing data or running queries, + though queries may temporarily return [stale results](../indexes/stale-indexes.mdx) until the index is fully updated. +**Separate storage**: + +* Indexes store their processed data separately, ensuring that the raw data remains unaffected. + This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance. + +* If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. + Learn more in [If indexes exhaust system resources](../indexes/what-are-indexes.mdx#if-indexes-exhaust-system-resources). + + + +## Types of indexes + +* Indexes in RavenDB are categorized along the following axes: + * **Auto** indexes -vs- **Static** indexes + * **Map** indexes -vs- **Map-Reduce** indexes + * **Single-Collection** (Single-Map) indexes -vs- **Multi-Collection** (Multi-Map) indexes + +* For a detailed description of each type, refer to section [Index types](../studio/database/indexes/indexes-overview.mdx#index-types). + + + +## Basic example + +In this example we create a static-index that indexes content from documents in the `Employees` [collection](../client-api/faq/what-is-a-collection.mdx). +This allows querying for _Employee_ documents by any of the index-fields (`FullName`, `LastName`, `Country`). + + + +#### Define the index + +* The first step is to define the index. + One way to do this is by inheriting from `AbstractIndexCreationTask`. + Learn more in [Define a static-index using a custom class](../indexes/creating-and-deploying.mdx#define-a-static-index-using-a-custom-class). +* Other methods to create a static-index are: + * [Creating a static-index using an Operation](../client-api/operations/maintenance/indexes/put-indexes.mdx) + * [Creating a static-index from the Studio](../studio/database/indexes/indexes-list-view.mdx) + + + +{`# Define the index: +# ================= + +class Employees_ByNameAndCountry(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + + self.map = """ + from employee in docs.Employees + select new \{ + LastName = employee.LastName, + FullName = employee.FirstName + " " + employee.LastName, + Country = employee.Address.country + \} + """ +`} + + + + + + +#### Deploy the index + +* The next step is to deploy the index to the RavenDB server. + One way to do this is by calling `execute()` on the index instance. +* Additional methods for deploying static-indexes are described in [Deploy a static index](../indexes/creating-and-deploying.mdx#deploy-a-static-index). +* Once deployed, the indexing process will start indexing documents. + + + +{`# Deploy the index to the server: +# =============================== + +Employees_ByNameAndCountry().execute(store) +`} + + + + + + +#### Query the index + +* Now you can query the _Employees_ collection using the index. + In this example we query for _Employee_ documents, **filtering results based on index-fields** `LastName` and `Country`. + The results will include only the _Employee_ documents that match the query predicate. +* For detailed guidance on querying with an index, refer to the [Querying an index](../indexes/querying/query-index.mdx). + + + +{`# Query the database using the index: +# =================================== + +employeesFromUK = list( + session.query_index_type(Employees_ByNameAndCountry, Employee) + # Here we query for all Employee documents that are from the UK + # and have 'King' in their LastName field: + .where_equals("Country", "UK") + .where_equals("LastName", "King") +) +`} + + + + + + +## Understanding index query results + + + +A common mistake is treating indexes like SQL Views, but they are not analogous. +The results of a query for a given index are the **full raw documents** that match the query predicate, +and not just the indexed fields. + +This behavior can be changed by applying [Projections](../indexes/querying/projections.mdx), +which let you project the query results into selected fields instead of returning the entire document. + + +#### Viewing the resulting documents: + +For example, the results shown in the following image are the **documents** that match the query predicate. + +![Index query results - documents](../assets/index-query-results-1.png) + +1. This is the index query. + The query predicate filters the resulting documents based on the content of the index-fields. +2. Each row in the results represents a **matching document**. +3. In this example, the `LastName`, `FirstName`, `Title`, etc., are the raw **document-fields**. +#### Viewing the index-entries: + +If you wish to **view the index-entries** that compose the index itself, +you can enable the option to show "raw index entries" instead of the matching documents. + +![Index query results - index entries](../assets/index-query-results-2.png) + +1. Query the index (no filtering is applied in this example). +2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents". +3. Each row in the results represents an **index-entry**. +4. In this example, the `Country`, `FullName`, and `LastName` columns are the **index-fields**, + which were defined in the index definition. +5. This a **term**. + In this example, `usa` is a term generated by the analyzer for index-field `Country` from document `employees/4-a`. + + + +## If indexes exhaust system resources + +* The indexing process utilizes machine resources to keep the data up-to-date for queries. + +* If indexing drains system resources, it may indicate one or more of the following: + * Indexes may have been defined in a way that causes inefficient processing. + * The [license](https://ravendb.net/buy) may need to be upgraded, + * Your [cloud instance](/cloud/cloud-instances#a-production-cloud-cluster) (if used) may require optimization. + * Hardware upgrades may be necessary to better support your workload. + +* Refer to the [Indexing Performance View](../studio/database/indexes/indexing-performance.mdx) in the Studio to monitor and analyze the indexing process. + This view provides graphical representations and detailed statistics of all index activities at each stage. + +* Additionally, refer to the [Common indexing issues](../studio/database/indexes/indexing-performance.mdx#common-indexing-issues) section + for troubleshooting and resolving indexing challenges. + + + + diff --git a/versioned_docs/version-7.1/indexes/creating-and-deploying.mdx b/versioned_docs/version-7.1/indexes/creating-and-deploying.mdx index f30be94812..82dfde3aa3 100644 --- a/versioned_docs/version-7.1/indexes/creating-and-deploying.mdx +++ b/versioned_docs/version-7.1/indexes/creating-and-deploying.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import CreatingAndDeployingCsharp from './_creating-and-deploying-csharp.mdx'; -import CreatingAndDeployingJava from './_creating-and-deploying-java.mdx'; -import CreatingAndDeployingNodejs from './_creating-and-deploying-nodejs.mdx'; +import CreatingAndDeployingCsharp from './content/_creating-and-deploying-csharp.mdx'; +import CreatingAndDeployingJava from './content/_creating-and-deploying-java.mdx'; +import CreatingAndDeployingNodejs from './content/_creating-and-deploying-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/extending-indexes.mdx b/versioned_docs/version-7.1/indexes/extending-indexes.mdx index c8f4e02e47..9336c4eef0 100644 --- a/versioned_docs/version-7.1/indexes/extending-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/extending-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExtendingIndexesCsharp from './_extending-indexes-csharp.mdx'; -import ExtendingIndexesJava from './_extending-indexes-java.mdx'; -import ExtendingIndexesNodejs from './_extending-indexes-nodejs.mdx'; +import ExtendingIndexesCsharp from './content/_extending-indexes-csharp.mdx'; +import ExtendingIndexesJava from './content/_extending-indexes-java.mdx'; +import ExtendingIndexesNodejs from './content/_extending-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-basics.mdx b/versioned_docs/version-7.1/indexes/indexing-basics.mdx index e2c06687b6..345d74896e 100644 --- a/versioned_docs/version-7.1/indexes/indexing-basics.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-basics.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingBasicsCsharp from './_indexing-basics-csharp.mdx'; -import IndexingBasicsJava from './_indexing-basics-java.mdx'; -import IndexingBasicsNodejs from './_indexing-basics-nodejs.mdx'; +import IndexingBasicsCsharp from './content/_indexing-basics-csharp.mdx'; +import IndexingBasicsJava from './content/_indexing-basics-java.mdx'; +import IndexingBasicsNodejs from './content/_indexing-basics-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-hierarchical-data.mdx b/versioned_docs/version-7.1/indexes/indexing-hierarchical-data.mdx index 506d7a2654..fdd2771d06 100644 --- a/versioned_docs/version-7.1/indexes/indexing-hierarchical-data.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-hierarchical-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingHierarchicalDataJava from './_indexing-hierarchical-data-java.mdx'; -import IndexingHierarchicalDataCsharp from './_indexing-hierarchical-data-csharp.mdx'; -import IndexingHierarchicalDataPython from './_indexing-hierarchical-data-python.mdx'; -import IndexingHierarchicalDataPhp from './_indexing-hierarchical-data-php.mdx'; -import IndexingHierarchicalDataNodejs from './_indexing-hierarchical-data-nodejs.mdx'; +import IndexingHierarchicalDataJava from './content/_indexing-hierarchical-data-java.mdx'; +import IndexingHierarchicalDataCsharp from './content/_indexing-hierarchical-data-csharp.mdx'; +import IndexingHierarchicalDataPython from './content/_indexing-hierarchical-data-python.mdx'; +import IndexingHierarchicalDataPhp from './content/_indexing-hierarchical-data-php.mdx'; +import IndexingHierarchicalDataNodejs from './content/_indexing-hierarchical-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-linq-extensions.mdx b/versioned_docs/version-7.1/indexes/indexing-linq-extensions.mdx index 4b157d443d..1314a64f4a 100644 --- a/versioned_docs/version-7.1/indexes/indexing-linq-extensions.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-linq-extensions.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingLinqExtensionsCsharp from './_indexing-linq-extensions-csharp.mdx'; -import IndexingLinqExtensionsJava from './_indexing-linq-extensions-java.mdx'; -import IndexingLinqExtensionsNodejs from './_indexing-linq-extensions-nodejs.mdx'; +import IndexingLinqExtensionsCsharp from './content/_indexing-linq-extensions-csharp.mdx'; +import IndexingLinqExtensionsJava from './content/_indexing-linq-extensions-java.mdx'; +import IndexingLinqExtensionsNodejs from './content/_indexing-linq-extensions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-metadata.mdx b/versioned_docs/version-7.1/indexes/indexing-metadata.mdx index 0906c90c41..6dad73917f 100644 --- a/versioned_docs/version-7.1/indexes/indexing-metadata.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-metadata.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingMetadataCsharp from './_indexing-metadata-csharp.mdx'; -import IndexingMetadataJava from './_indexing-metadata-java.mdx'; -import IndexingMetadataPython from './_indexing-metadata-python.mdx'; -import IndexingMetadataPhp from './_indexing-metadata-php.mdx'; -import IndexingMetadataNodejs from './_indexing-metadata-nodejs.mdx'; +import IndexingMetadataCsharp from './content/_indexing-metadata-csharp.mdx'; +import IndexingMetadataJava from './content/_indexing-metadata-java.mdx'; +import IndexingMetadataPython from './content/_indexing-metadata-python.mdx'; +import IndexingMetadataPhp from './content/_indexing-metadata-php.mdx'; +import IndexingMetadataNodejs from './content/_indexing-metadata-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-nested-data.mdx b/versioned_docs/version-7.1/indexes/indexing-nested-data.mdx index fb82cbfe77..fd815ee652 100644 --- a/versioned_docs/version-7.1/indexes/indexing-nested-data.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-nested-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingNestedDataCsharp from './_indexing-nested-data-csharp.mdx'; -import IndexingNestedDataJava from './_indexing-nested-data-java.mdx'; -import IndexingNestedDataPython from './_indexing-nested-data-python.mdx'; -import IndexingNestedDataPhp from './_indexing-nested-data-php.mdx'; -import IndexingNestedDataNodejs from './_indexing-nested-data-nodejs.mdx'; +import IndexingNestedDataCsharp from './content/_indexing-nested-data-csharp.mdx'; +import IndexingNestedDataJava from './content/_indexing-nested-data-java.mdx'; +import IndexingNestedDataPython from './content/_indexing-nested-data-python.mdx'; +import IndexingNestedDataPhp from './content/_indexing-nested-data-php.mdx'; +import IndexingNestedDataNodejs from './content/_indexing-nested-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-polymorphic-data.mdx b/versioned_docs/version-7.1/indexes/indexing-polymorphic-data.mdx index 33ef2849fa..e74f0df66b 100644 --- a/versioned_docs/version-7.1/indexes/indexing-polymorphic-data.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-polymorphic-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingPolymorphicDataCsharp from './_indexing-polymorphic-data-csharp.mdx'; -import IndexingPolymorphicDataJava from './_indexing-polymorphic-data-java.mdx'; -import IndexingPolymorphicDataPython from './_indexing-polymorphic-data-python.mdx'; -import IndexingPolymorphicDataPhp from './_indexing-polymorphic-data-php.mdx'; -import IndexingPolymorphicDataNodejs from './_indexing-polymorphic-data-nodejs.mdx'; +import IndexingPolymorphicDataCsharp from './content/_indexing-polymorphic-data-csharp.mdx'; +import IndexingPolymorphicDataJava from './content/_indexing-polymorphic-data-java.mdx'; +import IndexingPolymorphicDataPython from './content/_indexing-polymorphic-data-python.mdx'; +import IndexingPolymorphicDataPhp from './content/_indexing-polymorphic-data-php.mdx'; +import IndexingPolymorphicDataNodejs from './content/_indexing-polymorphic-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-related-documents.mdx b/versioned_docs/version-7.1/indexes/indexing-related-documents.mdx index 5701d642c3..f5126fc054 100644 --- a/versioned_docs/version-7.1/indexes/indexing-related-documents.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-related-documents.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingRelatedDocumentsJava from './_indexing-related-documents-java.mdx'; -import IndexingRelatedDocumentsCsharp from './_indexing-related-documents-csharp.mdx'; -import IndexingRelatedDocumentsPython from './_indexing-related-documents-python.mdx'; -import IndexingRelatedDocumentsPhp from './_indexing-related-documents-php.mdx'; -import IndexingRelatedDocumentsNodejs from './_indexing-related-documents-nodejs.mdx'; +import IndexingRelatedDocumentsJava from './content/_indexing-related-documents-java.mdx'; +import IndexingRelatedDocumentsCsharp from './content/_indexing-related-documents-csharp.mdx'; +import IndexingRelatedDocumentsPython from './content/_indexing-related-documents-python.mdx'; +import IndexingRelatedDocumentsPhp from './content/_indexing-related-documents-php.mdx'; +import IndexingRelatedDocumentsNodejs from './content/_indexing-related-documents-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/indexing-spatial-data.mdx b/versioned_docs/version-7.1/indexes/indexing-spatial-data.mdx index 090cf5be17..4e3d349364 100644 --- a/versioned_docs/version-7.1/indexes/indexing-spatial-data.mdx +++ b/versioned_docs/version-7.1/indexes/indexing-spatial-data.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IndexingSpatialDataCsharp from './_indexing-spatial-data-csharp.mdx'; -import IndexingSpatialDataJava from './_indexing-spatial-data-java.mdx'; -import IndexingSpatialDataPython from './_indexing-spatial-data-python.mdx'; -import IndexingSpatialDataPhp from './_indexing-spatial-data-php.mdx'; -import IndexingSpatialDataNodejs from './_indexing-spatial-data-nodejs.mdx'; +import IndexingSpatialDataCsharp from './content/_indexing-spatial-data-csharp.mdx'; +import IndexingSpatialDataJava from './content/_indexing-spatial-data-java.mdx'; +import IndexingSpatialDataPython from './content/_indexing-spatial-data-python.mdx'; +import IndexingSpatialDataPhp from './content/_indexing-spatial-data-php.mdx'; +import IndexingSpatialDataNodejs from './content/_indexing-spatial-data-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/javascript-indexes.mdx b/versioned_docs/version-7.1/indexes/javascript-indexes.mdx index c3823fd587..d5a516c218 100644 --- a/versioned_docs/version-7.1/indexes/javascript-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/javascript-indexes.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import JavascriptIndexesCsharp from './_javascript-indexes-csharp.mdx'; -import JavascriptIndexesJava from './_javascript-indexes-java.mdx'; +import JavascriptIndexesCsharp from './content/_javascript-indexes-csharp.mdx'; +import JavascriptIndexesJava from './content/_javascript-indexes-java.mdx'; diff --git a/versioned_docs/version-7.1/indexes/map-indexes.mdx b/versioned_docs/version-7.1/indexes/map-indexes.mdx index 7a15688973..53e579b03c 100644 --- a/versioned_docs/version-7.1/indexes/map-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapIndexesCsharp from './_map-indexes-csharp.mdx'; -import MapIndexesJava from './_map-indexes-java.mdx'; -import MapIndexesPython from './_map-indexes-python.mdx'; -import MapIndexesPhp from './_map-indexes-php.mdx'; -import MapIndexesNodejs from './_map-indexes-nodejs.mdx'; +import MapIndexesCsharp from './content/_map-indexes-csharp.mdx'; +import MapIndexesJava from './content/_map-indexes-java.mdx'; +import MapIndexesPython from './content/_map-indexes-python.mdx'; +import MapIndexesPhp from './content/_map-indexes-php.mdx'; +import MapIndexesNodejs from './content/_map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/map-reduce-indexes.mdx b/versioned_docs/version-7.1/indexes/map-reduce-indexes.mdx index b783b56532..eb29118146 100644 --- a/versioned_docs/version-7.1/indexes/map-reduce-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/map-reduce-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MapReduceIndexesCsharp from './_map-reduce-indexes-csharp.mdx'; -import MapReduceIndexesJava from './_map-reduce-indexes-java.mdx'; -import MapReduceIndexesPython from './_map-reduce-indexes-python.mdx'; -import MapReduceIndexesPhp from './_map-reduce-indexes-php.mdx'; -import MapReduceIndexesNodejs from './_map-reduce-indexes-nodejs.mdx'; +import MapReduceIndexesCsharp from './content/_map-reduce-indexes-csharp.mdx'; +import MapReduceIndexesJava from './content/_map-reduce-indexes-java.mdx'; +import MapReduceIndexesPython from './content/_map-reduce-indexes-python.mdx'; +import MapReduceIndexesPhp from './content/_map-reduce-indexes-php.mdx'; +import MapReduceIndexesNodejs from './content/_map-reduce-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/multi-map-indexes.mdx b/versioned_docs/version-7.1/indexes/multi-map-indexes.mdx index 8cf8ba4cc2..1bf75d3899 100644 --- a/versioned_docs/version-7.1/indexes/multi-map-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/multi-map-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MultiMapIndexesCsharp from './_multi-map-indexes-csharp.mdx'; -import MultiMapIndexesJava from './_multi-map-indexes-java.mdx'; -import MultiMapIndexesPython from './_multi-map-indexes-python.mdx'; -import MultiMapIndexesPhp from './_multi-map-indexes-php.mdx'; -import MultiMapIndexesNodejs from './_multi-map-indexes-nodejs.mdx'; +import MultiMapIndexesCsharp from './content/_multi-map-indexes-csharp.mdx'; +import MultiMapIndexesJava from './content/_multi-map-indexes-java.mdx'; +import MultiMapIndexesPython from './content/_multi-map-indexes-python.mdx'; +import MultiMapIndexesPhp from './content/_multi-map-indexes-php.mdx'; +import MultiMapIndexesNodejs from './content/_multi-map-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/number-type-conversion.mdx b/versioned_docs/version-7.1/indexes/number-type-conversion.mdx index 5e3ee851fc..0640697fce 100644 --- a/versioned_docs/version-7.1/indexes/number-type-conversion.mdx +++ b/versioned_docs/version-7.1/indexes/number-type-conversion.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import NumberTypeConversionCsharp from './_number-type-conversion-csharp.mdx'; +import NumberTypeConversionCsharp from './content/_number-type-conversion-csharp.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/_faceted-search-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/_faceted-search-csharp.mdx deleted file mode 100644 index 21157296fd..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_faceted-search-csharp.mdx +++ /dev/null @@ -1,1052 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`public class Camera -{ - public string Manufacturer { get; set; } - public double Cost { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } -} -`} - - - - -{`public class Cameras_ByFeatures : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string Brand { get; set; } - public double Price { get; set; } - public double MegaPixels { get; set; } - public int MaxFocalLength { get; set; } - public int UnitsInStock { get; set; } - } - - public Cameras_ByFeatures() - { - Map = cameras => from camera in cameras - select new - { - Brand = camera.Manufacturer, - Price = camera.Cost, - MegaPixels = camera.MegaPixels, - MaxFocalLength = camera.MaxFocalLength, - UnitsInStock = camera.UnitsInStock - }; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -var cameras = new[] -{ - new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, - new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, - new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, - new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, - new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, - new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, - new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, - new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, - new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, - new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, - new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, - new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } -}; - -using (var session = store.OpenSession()) -{ - foreach (var camera in cameras) - { - session.Store(camera); - } - - session.SaveChanges(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -List facets = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - // e.g. get the number of Camera documents for each unique Brand - FieldName = "Brand", - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Brand" - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - // Specify ranges within an index-field in order to get count per RANGE - // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - // Set a display name for this field in the results (optional) - DisplayFieldName = "Camera Price" - \} -\}; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facets) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Brand")) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Set a display name for the field in the results (optional) - .WithDisplayName("Camera Price")) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dictionary` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -var brandFacets = results["Camera Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("canon", facetValue.Range); -// Number of documents for 'Canon' is available in the 'Count' property -Assert.Equal(1, facetValue.Count); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -var priceFacets = results["Camera Price"]; -var numberOfRanges = priceFacets.Values.Count; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.Values[0]; -Assert.Equal("Price < 200", facetValue.Range); // The range string -Assert.Equal(3, facetValue.Count); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`Dictionary filteredResults = session - .Query() - // Limit query results to the selected brands: - .Where(x => x.Brand.In("Fuji", "Nikon")) - .AggregateBy(facets) - .Execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithOptions = new List -\{ - // Define a Facet: - new Facet - \{ - // Specify the index-field for which to get count of documents per unique ITEM - FieldName = "Brand", - // Set some facets options - Options = new FacetOptions - \{ - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithOptions) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the facets options - .WithOptions(new FacetOptions - { - // Return the top 3 brands with most items count: - PageSize = 3, - TermSortMode = FacetTermSortMode.CountDesc - })) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(Brand, $p0)") - // Add the facet options to the "p0" parameter - .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -var brandFacets = results["Brand"]; -var numberOfBrands = brandFacets.Values.Count; // 3 brands - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -Assert.Equal("fuji", facetValue.Range); -// Number of documents for 'Fuji' is available in the 'Count' property -Assert.Equal(4, facetValue.Count); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -List facetsWithAggregations = new List -\{ - // Define a Facet: - // =============== - new Facet - \{ - FieldName = "Brand", - Aggregations = - \{ - \{ - // Set the aggregation operation: - FacetAggregation.Sum, - // Create a HasSet specifying the index-fields for which to perform the aggregation - new HashSet - \{ - // Get total number of UnitsInStock per Brand - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price per Brand - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels per Brand - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength per Brand - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \}, - - // Define a RangeFacet: - // ==================== - new RangeFacet - \{ - Ranges = - \{ - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800 - \}, - Aggregations = - \{ - \{ - FacetAggregation.Sum, new HashSet - \{ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField \{Name = "UnitsInStock"\} - \} - \}, - \{ - FacetAggregation.Average, new HashSet - \{ - // Get average Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Min, new HashSet - \{ - // Get min Price of each group of documents per range specified - new FacetAggregationField \{Name = "Price"\} - \} - \}, - \{ - FacetAggregation.Max, new HashSet - \{ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField \{Name = "MegaPixels"\}, - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField \{Name = "MaxFocalLength"\} - \} - \} - \} - \} -\}; -`} - - -#### Query the index for facets results: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .AggregateBy(facetsWithAggregations) - .Execute(); -`} - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - .AggregateBy(builder => builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - .ByField(x => x.Brand) - // Specify the aggregations per the Brand facet: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .AndAggregateBy(builder => builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .ByRanges( - x => x.Price < 200, - x => x.Price >= 200 && x.Price < 400, - x => x.Price >= 400 && x.Price < 600, - x => x.Price >= 600 && x.Price < 800, - x => x.Price >= 800) - // Specify the aggregations per the Price range: - .SumOn(x => x.UnitsInStock) - .AverageOn(x => x.Price) - .MinOn(x => x.Price) - .MaxOn(x => x.MegaPixels) - .MaxOn(x => x.MaxFocalLength)) - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))") - // Add the parameters' values - .AddParameter("p0", 200.0) - .AddParameter("p1", 200.0) - .AddParameter("p2", 400.0) - .AddParameter("p3", 400.0) - .AddParameter("p4", 600.0) - .AddParameter("p5", 600.0) - .AddParameter("p6", 800.0) - .AddParameter("p7", 800.0) - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -var brandFacets = results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -var facetValue = brandFacets.Values[0]; -// The brand name is available in the 'Range' property: -Assert.Equal("canon", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(30, facetValue.Sum); - -// Get results for the 'Price' RangeFacets: -// ======================================= -var priceRangeFacets = results["Price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.Values[0]; -// The range string is available in the 'Range' property: -Assert.Equal("Price < 200.0", facetValue.Range); -// The index-field on which aggregation was done is in the 'Name' property: -Assert.Equal("UnitsInStock", facetValue.Name); -// The requested aggregation result: -Assert.Equal(17, facetValue.Sum); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -FacetSetup facetSetup = new FacetSetup -\{ - // Provide the ID of the document in which the facet setup will be stored. - // This is optional - - // if not provided then the session will assign an ID for the stored document. - Id = "customDocumentID", - - // Define Facets and RangeFacets to query by: - Facets = new List \{ - new Facet() - \{ - FieldName = "Brand" - \}\}, - - RangeFacets = new List - \{ - new RangeFacet - \{ - Ranges = - \{ - x => x.MegaPixels < 20, - x => x.MegaPixels >= 20 && x.MegaPixels < 30, - x => x.MegaPixels >= 30 && x.MegaPixels < 50, - x => x.MegaPixels >= 50 - \} - \} - \} -\}; - -// Store the facet setup document and save changes: -// ================================================ -session.Store(facetSetup); -session.SaveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`Dictionary results = session - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = await asyncSession - // Query the index - .Query() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .ExecuteAsync(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - .DocumentQuery() - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - .AggregateUsing("customDocumentID") - .Execute(); -`} - - - - -{`Dictionary results = session.Advanced - // Query the index - // Provide the RQL string to the RawQuery method - .RawQuery(@"from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))") - // Execute the query - .ExecuteAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`IAggregationQuery AggregateBy(FacetBase facet); -IAggregationQuery AggregateBy(IEnumerable facets); -IAggregationQuery AggregateBy(Action> builder); -IAggregationQuery AggregateUsing(string facetSetupDocumentKey); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | -| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`public class Facet -{ - public string FieldName { get; set; } - public FacetOptions Options { get; set; } -} - -public class Facet -{ - public Expression> FieldName { get; set; } - public FacetOptions Options { get; set; } -} -`} - - - - -{`public class RangeFacet -{ - public List Ranges { get; set; } -} - -public class RangeFacet -{ - public List>> Ranges { get; set; } -} -`} - - - - -{`public class FacetBase -{ - public Dictionary> Aggregations { get; set; } - public string DisplayFieldName { get; set; } -} -`} - - - - -{`public enum FacetAggregation -{ - None, - Max, - Min, - Average, - Sum -} -`} - - - - -**Fluent API builder methods**: - - - -{`IFacetOperations ByField(string fieldName); -IFacetOperations ByField(Expression> path); -IFacetOperations ByRanges(Expression> path, params Expression>[] paths); -IFacetOperations WithDisplayName(string displayName); -IFacetOperations WithOptions(FacetOptions options); -IFacetOperations SumOn(Expression> path); -IFacetOperations MinOn(Expression> path); -IFacetOperations MaxOn(Expression> path); -IFacetOperations AverageOn(Expression> path); -`} - - - -| Parameter | Type | Description | -|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`public class FacetOptions -\{ - public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; - public bool IncludeRemainingTerms \{ get; set; \} - public int Start \{ get; set; \} - public int PageSize \{ get; set; \} = int.MaxValue; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **Start** | `int` | The position from which to send items (how many to skip) | -| **PageSize** | `int` | Number of items to return | -| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_faceted-search-java.mdx b/versioned_docs/version-7.1/indexes/querying/_faceted-search-java.mdx deleted file mode 100644 index 23d8f77340..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_faceted-search-java.mdx +++ /dev/null @@ -1,362 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -When displaying a large amount of data, paging is often used to make viewing the data manageable. -It's also useful to give some context of the entire data-set and a easy way to drill-down into -particular categories. The common approach to doing this is a "faceted search", as shown in the -image below. **Note** how the count of each category within the current search is across the top. - -![Facets](./assets/CNET_faceted_search.jpg) - -<br /> -Let's start with defining a document like this: - - - -{`public class Camera \{ - private Date dateOfListing; - private String model; - private double cost; - private int zoom; - private double megapixels; - private boolean imageStabilizer; - private String manufacturer; - - public Date getDateOfListing() \{ - return dateOfListing; - \} - - public void setDateOfListing(Date dateOfListing) \{ - this.dateOfListing = dateOfListing; - \} - - public String getModel() \{ - return model; - \} - - public void setModel(String model) \{ - this.model = model; - \} - - public double getCost() \{ - return cost; - \} - - public void setCost(double cost) \{ - this.cost = cost; - \} - - public int getZoom() \{ - return zoom; - \} - - public void setZoom(int zoom) \{ - this.zoom = zoom; - \} - - public double getMegapixels() \{ - return megapixels; - \} - - public void setMegapixels(double megapixels) \{ - this.megapixels = megapixels; - \} - - public boolean isImageStabilizer() \{ - return imageStabilizer; - \} - - public void setImageStabilizer(boolean imageStabilizer) \{ - this.imageStabilizer = imageStabilizer; - \} - - public String getManufacturer() \{ - return manufacturer; - \} - - public void setManufacturer(String manufacturer) \{ - this.manufacturer = manufacturer; - \} -\} -`} - - - -## Step 1 - -Create an index to work against. - - - -{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ - public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ - map = "from camera in docs.Cameras " + - "select new \{" + - " camera.manufacturer," + - " camera.model," + - " camera.cost," + - " camera.dateOfListing," + - " camera.megapixels" + - "\} "; - \} -\} -`} - - - -## Step 2 - -Setup your facet definitions: - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - -This tells RavenDB that you would like to get the following facets: - -* For the **manufacturer** field, look at the documents and return a count for each unique Term found. - -* For the **cost** field, return the count of the following ranges: - - * cost < 200.0 - * 200.0 <= cost < 400.0 - * 400.0 <= cost < 600.0 - * 600.0 <= cost < 800.0 - * cost >= 800.0 -* For the **megapixels** field, return the count of the following ranges: - * megapixels <= 3.0 - * 3.0 <= megapixels < 7.0 - * 7.0 <= megapixels < 10.0 - * megapixels >= 10.0 - -## Step 3 - -You can write the following code to get back the data below: - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateBy(facets) - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) -`} - - - - -This data represents the sample faceted data that satisfies the above query: - - - -{`[ - \{ - "Name": "manufacturer", - "Values": [ - \{ - "Count": 1, - "Range": "canon" - \}, - \{ - "Count": 2, - "Range": "jessops" - \}, - \{ - "Count": 1, - "Range": "nikon" - \}, - \{ - "Count": 1, - "Range": "phillips" - \}, - \{ - "Count": 3, - "Range": "sony" - \} - ] - \}, - \{ - "Name": "cost", - "Values": [ - \{ - "Count": 6, - "Range": "cost <= 200" - \}, - \{ - "Count": 2, - "Range": "cost between 200 and 400" - \}, - \{ - "Count": 0, - "Range": "cost between 400 and 600" - \}, - \{ - "Count": 0, - "Range": "cost between 600 and 800" - \}, - \{ - "Count": 0, - "Range": "cost >= 800" - \} - ] - \}, - \{ - "Name": "megapixels", - "Values": [ - \{ - "Count": 0, - "Range": "megapixels <= 3" - \}, - \{ - "Count": 6, - "Range": "megapixels between 3 and 7" - \}, - \{ - "Count": 1, - "Range": "megapixels between 7 and 10" - \}, - \{ - "Count": 1, - "Range": "megapixels >= 10" - \} - ] - \} -] -`} - - - -### Storing Facets - -If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: - - - -{`FacetSetup facetSetup = new FacetSetup(); -facetSetup.setFacets(facets); -facetSetup.setRangeFacets(rangeFacets); - -session.store(facetSetup, "facets/CameraFacets"); -`} - - - - - - -{`Map facetResults = session - .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) - .whereBetween("cost", 100, 300) - .aggregateUsing("facets/CameraFacets") - .execute(); -`} - - - - -{`Facet facet1 = new Facet(); -facet1.setFieldName("manufacturer"); - -RangeFacet facet2 = new RangeFacet(); -facet2.setRanges(Arrays.asList( - "cost <= 200", - "cost between 200 and 400", - "cost between 400 and 600", - "cost between 600 and 800", - "cost >= 800" -)); - -RangeFacet facet3 = new RangeFacet(); -facet3.setRanges(Arrays.asList( - "megapixels < 3", - "megapixels between 3 and 7", - "megapixels between 7 and 10", - "megapixels >= 10" -)); - -List facets = Arrays.asList(facet1); -List rangeFacets = Arrays.asList(facet2, facet3); -`} - - - - -{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' -where cost between 100 and 300 -select facet(id('facets/CameraFacets')) -`} - - - - -### Stale Results - -The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. - -### Fluent API - -As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). - - diff --git a/versioned_docs/version-7.1/indexes/querying/_faceted-search-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/_faceted-search-nodejs.mdx deleted file mode 100644 index 3522cec64d..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_faceted-search-nodejs.mdx +++ /dev/null @@ -1,918 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera { - constructor( - manufacturer = '', - cost = 0, - megaPixels = 0, - maxFocalLength = 0, - unitsInStock = 0 - ) { - Object.assign(this, { - manufacturer, - cost, - megaPixels, - maxFocalLength, - unitsInStock - }); - } -} -`} - - - - -{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { - constructor () { - super(); - - this.map("Cameras", camera => { - return { - brand: camera.manufacturer, - price: camera.cost, - megaPixels: camera.megaPixels, - maxFocalLength: camera.maxFocalLength, - unitsInStock: camera.unitsInStock - }; - }); - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== -const bulkInsert = store.bulkInsert(); - -const cameras = [ - new Camera("Sony", 100, 20.1, 200, 10), - new Camera("Sony", 200, 29, 250, 15), - new Camera("Nikon", 120, 22.3, 300, 2), - new Camera("Nikon", 180, 32, 300, 5), - new Camera("Nikon", 220, 40, 300, 20), - new Camera("Canon", 200, 30.4, 400, 30), - new Camera("Olympus", 250, 32.5, 600, 4), - new Camera("Olympus", 390, 40, 600, 6), - new Camera("Fuji", 410, 45, 700, 1), - new Camera("Fuji", 590, 45, 700, 5), - new Camera("Fuji", 650, 61, 800, 17), - new Camera("Fuji", 850, 102, 800, 19) -]; - -for (const camera of cameras) { - await bulkInsert.store(camera); -} - -await bulkInsert.finish(); -`} - - - - - - -## Facets - Basics - - - -**Facets definition**: -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a Facet: -// =============== -const brandFacet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique brand -brandFacet.fieldName = "brand"; -// Set a display name for this field in the results (optional) -brandFacet.displayFieldName = "Camera Brand"; - -// Define a RangeFacet: -// ==================== -const priceRangeFacet = new RangeFacet(); -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -priceRangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; -// Set a display name for this field in the results (optional) -priceRangeFacet.displayFieldName = "Camera Price"; - -const facets = [brandFacet, priceRangeFacet]; -`} - - - - - - - -**Query the index for facets results**: -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - .aggregateBy(...facets) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand")) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Set a display name for the field in the results (optional) - .withDisplayName("Camera Brand")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price"\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand) as "Camera Brand", - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800) as "Camera Price" -`} - - - - - - - - -**Query results**: -* **Query results** are Not the collection documents, they are of type `FacetResultObject` - which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'brand' using the display name specified: -// ============================================================================ -const brandFacets = results["Camera Brand"]; -const numberOfBrands = brandFacets.values.length; // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "canon"); -// Number of documents for 'Canon' is available in the 'count' property -assert.equal(facetValue.count, 1); - -// Get facets results for index-field 'price' using the display name specified: -// ============================================================================ -const priceFacets = results["Camera Price"]; -const numberOfRanges = priceFacets.values.length; // 5 different ranges - -// Get the aggregated facet value for a specific Range: -facetValue = priceFacets.values[0]; -assert.equal(facetValue.range, "price < 200"); // The range string -assert.equalfacetValue.count, 3); // Number of documents in this range -`} - - - - - - - -**Query further**: -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`const filteredResults = await session - .query(\{ indexName: "Cameras/ByFeatures" \}) - // Limit query results to the selected brands: - .whereIn("brand", ["Fuji", "Nikon"]) - .aggregateBy(...facets) - .execute(); -`} - - - - - - - -## Facets - Options - - - -**Facets definition**: -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `pageSize` - Number of items to return. - * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. - * `termSortMode` - Set the sort order on the resulting items. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -facet.fieldName = "brand"; - -// Set some facet options -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -facet.options = facetOptions; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(facet) - .execute(); -`} - - - - -{`// Set facet options to use in the following query -// E.g.: Return top 3 brands with most items count -const facetOptions = new FacetOptions(); -facetOptions.pageSize = 3; -facetOptions.termSortMode = "CountDesc"; - -const results = await session - //Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Call 'withOptions', pass the facets options - .withOptions(facetOptions)) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(brand, $p0)\`) - // Add the facet options to the "p0" parameter - .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(brand, $p0) -{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain: -// ================================= - -// For the "brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'brand': -// =========================================== -const brandFacets = results["brand"]; -const numberOfBrands = brandFacets.values.length; // 3 brands - -// Get the aggregated facet value for a specific Brand: -const facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -assert.equal(facetValue.range, "fuji"); -// Number of documents for 'Fuji' is available in the 'count' property -assert.equal(facetValue.count, 4); -`} - - - - - - - -## Facets - Aggregations - - - -**Facets definition**: -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of unitsInStock per Brand - * Get the highest megaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define a Facet: -// =============== -const facet = new Facet(); -facet.fieldName = "brand"; - -// Define the index-fields to aggregate: -const unitsInStockAggregationField = new FacetAggregationField(); -unitsInStockAggregationField.name = "unitsInStock"; - -const priceAggregationField = new FacetAggregationField(); -priceAggregationField.name = "price"; - -const megaPixelsAggregationField = new FacetAggregationField(); -megaPixelsAggregationField.name = "megaPixels"; - -const maxFocalLengthAggregationField = new FacetAggregationField(); -maxFocalLengthAggregationField.name = "maxFocalLength"; - -// Define the aggregation operations: -facet.aggregations.set("Sum", [unitsInStockAggregationField]); -facet.aggregations.set("Average", [priceAggregationField]); -facet.aggregations.set("Min", [priceAggregationField]); -facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -// Define a RangeFacet: -// ==================== -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "price < 200", - "price >= 200 and price < 400", - "price >= 400 and price < 600", - "price >= 600 and price < 800", - "price >= 800" -]; - -// Define the aggregation operations: -rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); -rangeFacet.aggregations.set("Average", [priceAggregationField]); -rangeFacet.aggregations.set("Min", [priceAggregationField]); -rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); - -const facetsWithAggregations = [facet, rangeFacet]; -`} - - - - - - - -**Query the index for facets results**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facet from above - .aggregateBy(...facetsWithAggregations) - .execute(); -`} - - - - -{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below -const range = RangeBuilder.forPath("price"); - -const results = await session - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateBy' to aggregate the data by facets - // Use a builder as follows: - .aggregateBy(builder => builder - // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .byField("brand") - // Specify the aggregations per the brand facet: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - // Call 'andAggregateBy' to aggregate the data by also by range-facets - // Use a builder as follows: - .andAggregateBy(builder => builder - .byRanges( - // Specify the ranges within index field 'price' in order to get count per RANGE - range.isLessThan(200), - range.isGreaterThanOrEqualTo(200).isLessThan(400), - range.isGreaterThanOrEqualTo(400).isLessThan(600), - range.isGreaterThanOrEqualTo(600).isLessThan(800), - range.isGreaterThanOrEqualTo(800)) - // Specify the aggregations per the price range: - .sumOn("unitsInStock") - .averageOn("price") - .minOn("price") - .maxOn("megaPixesls") - .maxOn("maxFocalLength")) - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength))\`) - // Add the parameters' values - .addParameter("p0", 200) - .addParameter("p1", 200) - .addParameter("p2", 400) - .addParameter("p3", 400) - .addParameter("p4", 600) - .addParameter("p5", 600) - .addParameter("p6", 800) - .addParameter("p7", 800) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(brand, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)), - facet(price < 200, - price >= 200 and price < 400, - price >= 400 and price < 600, - price >= 600 and price < 800, - price >= 800, - sum(unitsInStock), - avg(price), - min(price), - max(megaPixels), - max(maxFocalLength)) -`} - - - - - - - - -**Query results**: - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "brand" Facet: -// "canon" Count:1, Sum: 30, Name: unitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: price -// "canon" Count:1, Max: 30.4, Name: megaPixels -// "canon" Count:1, Max: 400, Name: maxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: unitsInStock -// "fuji" Count:4, Min: 410, Name: price -// "fuji" Count:4, Max: 102, Name: megaPixels -// "fuji" Count:4, Max: 800, Name: maxFocalLength -// -// etc..... - -// For the "price" Ranges: -// "Price < 200" Count:3, Sum: 17, Name: unitsInStock -// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price -// "Price < 200" Count:3, Max: 32, Name: megaPixels -// "Price < 200" Count:3, Max: 300, Name: maxFocalLength -// -// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock -// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price -// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels -// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'brand' Facets: -// ========================================== -const brandFacets = results["brand"]; - -// Get the aggregated facet value for a specific brand: -let facetValue = brandFacets.values[0]; -// The brand name is available in the 'range' property: -assert.equal(facetValue.range, "canon"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 30); - -// Get results for the 'price' RangeFacets: -// ======================================= -const priceRangeFacets = results["price"]; - -// Get the aggregated facet value for a specific Brand: -facetValue = priceRangeFacets.values[0]; -// The range string is available in the 'range' property: -assert.equal(facetValue.range, "price < 200"); -// The index-field on which aggregation was done is in the 'name' property: -assert.equal(facetValue.name, "unitsInStock"); -// The requested aggregation result: -assert.equal(facetValue.sum, 17); -`} - - - - - - - -## Storing facets definition in a document - - - - - -**Define and store facets in a document**: -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -const facetSetup = new FacetSetup(); - -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -facetSetup.id = "customDocumentID"; - -// Define Facets and RangeFacets to query by: -const facet = new Facet(); -facet.fieldName = 'brand'; - -facetSetup.facets = [facet]; - -const rangeFacet = new RangeFacet(); -rangeFacet.ranges = [ - "megaPixels < 20", - "megaPixels >= 20 and megaPixels < 30", - "megaPixels >= 30 and megaPixels < 50", - "megaPixels >= 50" -]; - -facetSetup.rangeFacets = [rangeFacet]; - -// Store the facet setup document and save changes: -// ================================================ -await session.store(facetSetup); -await session.saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - - - - - - -**Query using facets from document**: - - - -{`const results = await session - // Query the index - .query({ indexName: "Cameras/ByFeatures" }) - // Call 'aggregateUsing' - // Pass the ID of the document that contains your facets setup - .aggregateUsing("customDocumentID") - .execute(); -`} - - - - -{`const results = await session.advanced - // Query the index - // Provide the RQL string to the rawQuery method - .rawQuery(\`from index "Cameras/ByFeatures" - select facet(id("customDocumentID"))\`) - // Execute the query - .executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - - - -## Syntax - - - -{`// Aggregate data by Facets: -aggregateBy(facet); -aggregateBy(...facet); -aggregateBy(action); - -// Aditional aggregation for another Facet/RangeFacet (use with fluent API) -andAggregateBy(facet); -andAggregateBy(builder); - -// Aggregate data by Facets stored in a document -aggregateUsing(facetSetupDocumentId); -`} - - - -| Parameter | Type | Description | -|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| -| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | -| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | -| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | -| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | - - - - -{`class Facet { - fieldName; -} -`} - - - - -{`class RangeFacet { - ranges; -} -`} - - - - -{`class FacetBase { - displayFieldName; - options; - aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" -} -`} - - - - -**builder methods**: - - - -{`byField(fieldName); -byRanges(range, ...ranges); - -withDisplayName(displayName); -withOptions(options); - -sumOn(path); -sumOn(path, displayName); - -minOn(path); -minOn(path, displayName); - -maxOn(path); -maxOn(path, displayName); - -averageOn(path); -averageOn(path, displayName); -`} - - - -| Parameter | Type | Description | -|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - -**Options**: - - - -{`class FacetOptions \{ - termSortMode; - includeRemainingTerms; - start; - pageSize; -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | -| **start** | `number` | The position from which to send items (how many to skip) | -| **pageSize** | `number` | Number of items to return | -| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_faceted-search-php.mdx b/versioned_docs/version-7.1/indexes/querying/_faceted-search-php.mdx deleted file mode 100644 index 0fa8ffec23..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_faceted-search-php.mdx +++ /dev/null @@ -1,1094 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera -{ - private ?string $manufacturer = null; - private ?float $cost = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function __construct( - ?string $manufacturer = null, - ?float $cost = null, - ?float $megaPixels = null, - ?int $maxFocalLength = null, - ?int $unitsInStock = null, - ) - { - $this->manufacturer = $manufacturer; - $this->cost = $cost; - $this->megaPixels = $megaPixels; - $this->maxFocalLength = $maxFocalLength; - $this->unitsInStock = $unitsInStock; - } - - public function getManufacturer(): ?string - { - return $this->manufacturer; - } - - public function setManufacturer(?string $manufacturer): void - { - $this->manufacturer = $manufacturer; - } - - public function getCost(): ?float - { - return $this->cost; - } - - public function setCost(?float $cost): void - { - $this->cost = $cost; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} -`} - - - - -{`class Cameras_ByFeatures_IndexEntry -{ - private ?string $brand = null; - private ?float $price = null; - private ?float $megaPixels = null; - private ?int $maxFocalLength = null; - private ?int $unitsInStock = null; - - public function getBrand(): ?string - { - return $this->brand; - } - - public function setBrand(?string $brand): void - { - $this->brand = $brand; - } - - public function getPrice(): ?float - { - return $this->price; - } - - public function setPrice(?float $price): void - { - $this->price = $price; - } - - public function getMegaPixels(): ?float - { - return $this->megaPixels; - } - - public function setMegaPixels(?float $megaPixels): void - { - $this->megaPixels = $megaPixels; - } - - public function getMaxFocalLength(): ?int - { - return $this->maxFocalLength; - } - - public function setMaxFocalLength(?int $maxFocalLength): void - { - $this->maxFocalLength = $maxFocalLength; - } - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Cameras_ByFeatures extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = - "from camera in docs.Cameras " . - "select new " . - "{ " . - " brand = camera.manufacturer," . - " price = camera.cost," . - " megaPixels = camera.megaPixels," . - " maxFocalLength = camera.maxFocalLength," . - " unitsInStock = camera.unitsInStock" . - "}"; - } -} -`} - - - - -{`// Creating sample data for the examples in this article: -// ====================================================== - -$cameras = []; - -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); -$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); -$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); -$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); -$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); - -$session = $store->openSession(); -try { - foreach ($cameras as $camera) - { - $session->store($camera); - } - - $session->saveChanges(); -} finally { - $session->close(); -} -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets to aggregate the data by. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`// Define a list of facets to query by: -// ==================================== -$facets = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -// Specify the index-field for which to get count of documents per unique ITEM -// e.g. get the number of Camera documents for each unique Brand -$facet->setFieldName("Brand"); -// Set a display name for this field in the results (optional) -$facet->setDisplayFieldName("Camera Brand"); - -$facets[] = $facet; - -// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry -// ==================== -$rangeFacet = new RangeFacet(); - -// Specify ranges within an index-field in order to get count per RANGE -// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -$rangeFacet->setRanges([ - "price < 200", - "price >= 200 and price <= 400", - "price >= 400 and price <= 600", - "price >= 600 and price <= 800", - "price >= 800" -]); - -// Set a display name for this field in the results (optional) -$rangeFacet->setDisplayFieldName("Camera Price"); - -$facets[] = $rangeFacet; -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facets) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - return $builder - // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Brand"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Set a display name for the field in the results (optional) - ->withDisplayName("Camera Price"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand) as 'Camera Brand', - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as 'Camera Price'" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`// The resulting aggregations per display name will contain: -// ========================================================= - -// For the "Camera Brand" Facet: -// "canon" - Count: 1 -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 -// "sony" - Count: 2 - -// For the "Camera Price" Ranges: -// "Price < 200" - Count: 3 -// "Price >= 200.0 and Price < 400.0" - Count: 5 -// "Price >= 400.0 and Price < 600.0" - Count: 2 -// "Price >= 600.0 and Price < 800.0" - Count: 1 -// "Price >= 800.0" - Count: 1 -`} - - - - -{`// Get facets results for index-field 'Brand' using the display name specified: -// ============================================================================ -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Camera Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index - -$this->assertEquals("canon", $facetValue->getRange()); -// Number of documents for 'Canon' is available in the 'Count' property -$this->assertEquals(1, $facetValue->getCount()); - -// Get facets results for index-field 'Price' using the display name specified: -// ============================================================================ -/** @var FacetResult $priceFacets */ -$priceFacets = $results["Camera Price"]; -$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges - -// Get the aggregated facet value for a specific Range: -/** @var FacetValue $facetValue */ -$facetValue = $priceFacets->getValues()[0]; -$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string -$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`$filteredResults = $session - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Limit query results to the selected brands: - ->whereIn("Brand", ["Fuji", "Nikon"]) - ->aggregateBy($facets) - ->execute(); -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - * `Start` - The position from which to send items (how many to skip). - * `PageSize` - Number of items to return. - * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. - * `TermSortMode` - Set the sort order on the resulting items. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithOptions = []; - - // Define a Facet: -$facet = new Facet(); - -// Specify the index-field for which to get count of documents per unique ITEM -$facet->setFieldName("Brand"); - -// Set some facets options -$options = new FacetOptions(); -// Return the top 3 brands with most items count: -$options->setPageSize(3); -$options->setTermSortMode(FacetTermSortMode::countDesc()); - -$facet->setOptions($options); - -$facetsWithOptions[] = $facet; -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'aggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithOptions) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - $options = new FacetOptions(); - // Return the top 3 brands with most items count: - $options->setPageSize(3); - $options->setTermSortMode(FacetTermSortMode::countDesc()); - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the facets options - ->withOptions($options); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") - // Add the facet options to the "p0" parameter - ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`// The resulting items will contain: -// ================================= - -// For the "Brand" Facet: -// "fuji" - Count: 4 -// "nikon" - Count: 3 -// "olympus" - Count: 2 - -// As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`// Get facets results for index-field 'Brand': -// =========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; -$numberOfBrands = count($brandFacets->getValues()); // 3 brands - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property -// Note: value is lower-case since the default RavenDB analyzer was used by the index -$this::assertEquals("fuji", $facetValue->getRange()); -// Number of documents for 'Fuji' is available in the 'Count' property -$this->assertEquals(4, $facetValue->getCount()); -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * sum - * average - * min - * max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`// Define the list of facets to query by: -// ====================================== -$facetsWithAggregations = []; - -// Define a Facet: -// =============== -$facet = new Facet(); -$facet->setFieldName("Brand"); - -$aggregations = new AggregationArray(); - -$aggregations->set( - // Set the aggregation operation: - FacetAggregation::sum(), - // Get total number of UnitsInStock for each group of documents per range specified - [ - // Get total number of UnitsInStock per Brand - new FacetAggregationField($name = "UnitsInStock") - ] -); - -$aggregations->set(FacetAggregation::average(), [ - // Get average Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::min(), [ - // Get min Price per Brand - new FacetAggregationField($name = "Price") -]); - -$aggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels per Brand - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength per Brand - new FacetAggregationField($name = "MaxFocalLength") -]); - -$facet->setAggregations($aggregations); - -// Define a RangeFacet: -// ==================== -$rangeFacet = new RangeFacet(); -$rangeFacet->setRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" -]); - -$rangeAggregations = new AggregationArray(); - -$rangeAggregations->set(FacetAggregation::sum(), [ - // Get total number of UnitsInStock for each group of documents per range specified - new FacetAggregationField($name = "UnitsInStock") -]); -$rangeAggregations->set(FacetAggregation::average(), [ - // Get average Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); -$rangeAggregations->set(FacetAggregation::min(), [ - // Get min Price of each group of documents per range specified - new FacetAggregationField($name = "Price") -]); - -$rangeAggregations->set(FacetAggregation::max(), [ - // Get max MegaPixels for each group of documents per range specified - new FacetAggregationField($name = "MegaPixels"), - // Get max MaxFocalLength for each group of documents per range specified - new FacetAggregationField($name = "MaxFocalLength") - -]); - -$rangeFacet->setAggregations($rangeAggregations); -`} - - -#### Query the index for facets results: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Pass the defined facets from above - ->aggregateBy($facetsWithAggregations) - ->execute(); -`} - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateBy' to aggregate the data by facets - // Use a builder as follows: - ->aggregateBy(function($builder) { - - return $builder - // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM - ->byField("Brand") - // Specify the aggregations per the Brand facet: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->andAggregateBy(function($builder) { - return $builder - // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - ->byRanges([ - "Price < 200", - "Price >= 200 && Price < 400", - "Price >= 400 && Price < 600", - "Price >= 600 && Price < 800", - "Price >= 800" - ]) - // Specify the aggregations per the Price range: - ->sumOn("UnitsInStock") - ->averageOn("Price") - ->minOn("Price") - ->maxOn("MegaPixels") - ->maxOn("MaxFocalLength"); - }) - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery(Camera::class, - "from index 'Cameras/ByFeatures' - select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < \\$p0, - Price >= \\$p1 and Price < \\$p2, - Price >= \\$p3 and Price < \\$p4, - Price >= \\$p5 and Price < \\$p6, - Price >= \\$p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength))" - ) - // Add the parameters' values - ->addParameter("p0", 200.0) - ->addParameter("p1", 200.0) - ->addParameter("p2", 400.0) - ->addParameter("p3", 400.0) - ->addParameter("p4", 600.0) - ->addParameter("p5", 600.0) - ->addParameter("p6", 800.0) - ->addParameter("p7", 800.0) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`// The resulting items will contain (Showing partial results): -// =========================================================== - -// For the "Brand" Facet: -// "canon" Count:1, Sum: 30, Name: UnitsInStock -// "canon" Count:1, Min: 200, Average: 200, Name: Price -// "canon" Count:1, Max: 30.4, Name: MegaPixels -// "canon" Count:1, Max: 400, Name: MaxFocalLength -// -// "fuji" Count:4, Sum: 42, Name: UnitsInStock -// "fuji" Count:4, Min: 410, Name: Price -// "fuji" Count:4, Max: 102, Name: MegaPixels -// "fuji" Count:4, Max: 800, Name: MaxFocalLength -// -// etc..... - -// For the "Price" Ranges: -// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength -// -// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength -// -// etc..... -`} - - - - -{`// Get results for the 'Brand' Facets: -// ========================================== -/** @var FacetResult $brandFacets */ -$brandFacets = $results["Brand"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $brandFacets->getValues()[0]; -// The brand name is available in the 'Range' property: -$this->assertEquals("canon", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(30, $facetValue->getSum()); - -// Get results for the 'Price' RangeFacets: -// ======================================= -/** @var FacetResult $priceRangeFacets */ -$priceRangeFacets = $results["Price"]; - -// Get the aggregated facet value for a specific Brand: -/** @var FacetValue $facetValue */ -$facetValue = $priceRangeFacets->getValues()[0]; -// The range string is available in the 'Range' property: -$this->assertEquals("Price < 200.0", $facetValue->getRange()); -// The index-field on which aggregation was done is in the 'Name' property: -$this->assertEquals("UnitsInStock", $facetValue->getName()); -// The requested aggregation result: -$this->assertEquals(17, $facetValue->getSum()); -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`// Create a FacetSetup object: -// =========================== -$facetSetup = new FacetSetup(); -// Provide the ID of the document in which the facet setup will be stored. -// This is optional - -// if not provided then the session will assign an ID for the stored document. -$facetSetup->setId("customDocumentID"); - -// Define Facets and RangeFacets to query by: -$facetSetup->setFacets([ - new Facet("Brand") -]); - - -$facetSetup->setRangeFacets([ - new RangeFacet( - $parent = null, - $ranges = [ - "MegaPixels < 20", - "MegaPixels >= 20 && MegaPixels < 30", - "MegaPixels >= 30 && MegaPixels < 50", - "MegaPixels >= 50" - ] - ) -]); - -// Store the facet setup document and save changes: -// ================================================ -$session->store($facetSetup); -$session->saveChanges(); - -// The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`$results = $session - // Query the index - ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) - // Call 'AggregateUsing' - // Pass the ID of the document that contains your facets setup - ->aggregateUsing("customDocumentID") - ->execute(); -`} - - - - -{`$results = $session->advanced() - // Query the index - // Provide the RQL string to the RawQuery method - ->rawQuery( - $className = Camera::class, - $query = "from index 'Cameras/ByFeatures' - select facet(id('customDocumentID'))" - ) - // Execute the query - ->executeAggregation(); -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; - -// You can call it -// ->aggregateBy(FacetBase $facet); -// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); -// ->aggregateBy(FacetBaseArray|array $facets); -// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); - -public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | -| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | -| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | - - - - -{`class Facet -{ - private ?string $fieldName = null; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class RangeFacet -{ - private StringArray $ranges; - private ?FacetOptions $options = null; - - // ... getters and setters -} -`} - - - - -{`class FacetBase -{ - private ?AggregationArray $aggregations = null; - private ?string $displayFieldName = null; - - // ... getters and setters -} -`} - - - - -{`interface FacetAggregation -{ - public function isNone(): bool; - public function isMax(): bool; - public function isMin(): bool; - public function isAverage(): bool; - public function isSum(): bool; - - public static function none(): FacetAggregation; - public static function max(): FacetAggregation; - public static function min(): FacetAggregation; - public static function average(): FacetAggregation; - public static function sum(): FacetAggregation; -} -`} - - - - -**Fluent API builder methods**: - - - -{`public function byField(string $fieldName): FacetOperationsInterface; -public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; - -public function withDisplayName(string $displayName): FacetOperationsInterface; -public function withOptions(FacetOptions $options): FacetOperationsInterface; - -public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; -public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range** | `RangeBuilder` | A range of indexes | -| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **fieldName** | `string` | The index-field to use for the facet | -| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **displayName** | `string` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions -\{ - private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() - private bool $includeRemainingTerms = false; - private int $start = 0; - private int $pageSize = 0; - - // ... getters and setters -\} -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **pageSize** | `int` | Number of items to return | -| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_faceted-search-python.mdx b/versioned_docs/version-7.1/indexes/querying/_faceted-search-python.mdx deleted file mode 100644 index 0a7c6a2f00..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_faceted-search-python.mdx +++ /dev/null @@ -1,945 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. - -* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. - -![Facets](./assets/CNET_faceted_search.jpg) -* In this page - * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) - * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) - * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) - * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) - * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) - * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) - - -## Define an index - -* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. - -* The examples in this article will be based on the following Class, Index, and Sample Data: - - - - -{`class Camera: - def __init__( - self, - manufacturer: str = None, - cost: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.manufacturer = manufacturer - self.cost = cost - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock -`} - - - - -{`class Cameras_ByFeatures(AbstractIndexCreationTask): - class IndexEntry: - def __init__( - self, - brand: str = None, - price: float = None, - mega_pixels: float = None, - max_focal_length: int = None, - units_in_stock: int = None, - ): - self.brand = brand - self.price = price - self.mega_pixels = mega_pixels - self.max_focal_length = max_focal_length - self.units_in_stock = units_in_stock - - def __init__(self): - super().__init__() - self.map = ( - "from camera in docs.Cameras " - "select new " - "{ " - " brand = camera.manufacturer," - " price = camera.cost," - " mega_pixels = camera.mega_pixels," - " max_focal_length = camera.max_focal_length," - " units_in_stock = camera.units_in_stock" - "}" - ) -`} - - - - -{`# Creating sample data for the examples in this article: -# ====================================================== - -cameras = [ - Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), - Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), - Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), - Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), - Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), - Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), - Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), - Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), - Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), - Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), - Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), - Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), -] - -with store.open_session() as session: - for camera in cameras: - session.store(camera) - session.save_changes() -`} - - - - - - -## Facets - Basics - -#### Facets definition: - -* Define a list of facets by which to aggregate the data. - -* There are two **Facet types**: - * `Facet` - returns a count for each unique term found in the specified index-field. - * `RangeFacet` - returns a count per range within the specified index-field. - - - -{`# Define a Facet: -# =============== -facet = Facet( - # Specify the index-field for which to get count of documents per unique ITEM - # e.g. get the number of Camera documents for each unique brand - field_name="brand", -) - -# Set a display name for this field in the results (optional) -facet.display_field_name = "Camera Brand" - -# Define a RangeFacet: -# ==================== -range_facet = RangeFacet() -# Specify ranges within an index-field in order to get count per RANGE -# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... -range_facet.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] - -# Set a display name for this field in the results (optional) -range_facet.display_field_name = "Camera Price" - -# Define a list of facets to query by: -# ==================================== -facets = [facet, range_facet] -`} - - -#### Query the index for facets results: - -* Query the index to get the aggregated facets information. - -* Either: - - * Pass the facets definition from above directly to the query - - * Or - construct a facet using a builder with the Fluent API option, as shown below. - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets).execute() -) -`} - - - - -{`# Query the index -results = ( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Set a display name for the field in the results (optional) - .with_display_name("Camera Brand") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Set a display name for the field in the results (optional) - .with_display_name("Camera Price") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select - facet(brand) as 'Camera Brand', - facet(price < 200.0, - price >= 200.0 and price < 400.0, - price >= 400.0 and price < 600.0, - price >= 600.0 and price < 800.0, - price >= 800.0) as 'Camera Price'""", - object_type=Camera, - ) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand) as "Camera Brand", - facet(Price < 200.0, - Price >= 200.0 and Price < 400.0, - Price >= 400.0 and Price < 600.0, - Price >= 600.0 and Price < 800.0, - Price >= 800.0) as "Camera Price" -`} - - - -#### Query results: - -* **Query results** are Not the collection documents, they are of type: - `Dict[str, FacetResult]` which is the facets results per index-field specified. - -* Using the sample data from this article, the resulting aggregations will be: - - - -{`# The resulting aggregations per display name will contain: -# ========================================================= - -# For the "Camera Brand" Facet: -# "canon" - Count: 1 -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# "sony" - Count: 2 - -# For the "Camera Price" Ranges: -# "price < 200" - Count: 3 -# "200 <= price < 400" - Count: 5 -# "400 <= price < 600" - Count: 2 -# "600 <= price < 800" - Count: 1 -# "price >= 800" - Count: 1 -`} - - - - -{`# Get facets results for index-field 'brand' using the display name specified: -# ============================================================================ -brand_facets = results["Camera Brand"] -number_of_brands = len(brand_facets.values) # 5 unique brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("canon", facet_value.range_) -# Number of documents for 'Canon' is available in the 'Count' property -self.assertEqual(1, facet_value.count_) - -# Get facets results for index-field 'Price' using the display name specified: -# ============================================================================ -price_facets = results["Camera Price"] -number_of_ranges = len(price_facets.values) # 5 different ranges - -# Get the aggregated facet value for a specific Range: -facet_value = price_facets.values[0] -self.assertEqual("price < 200", facet_value.range_) # The range string -self.assertEqual(3, facet_value.count_) -`} - - - - - -**Query further**: - -* Typically, after presenting users with the initial facets results which show the available options, - users can select specific categories to explore further. - -* For example, if the user selects Fuji and Nikon, - then your next query can include a filter to focus only on those selected brands. - - - -{`filtered_results = list( - session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - .where_in("brand", ["Fuji", "Nikon"]) - .aggregate_by_facets(facets) - .execute() -) -`} - - - - - - - -## Facets - Options - -#### Facets definition: - -* **Options** are available only for the `Facet` type. - -* Available options: - - * `start` - The position from which to send items (how many to skip). - * `page_size` - Number of items to return. - * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. - * `term_sort_mode` - Set the sort order on the resulting items. - - - -{`# Define the list of facets to query by: -# ====================================== -facets_with_options = [ - # Define a Facet: - Facet( - # Specify the index-field for which to get count of documents per unique ITEM - field_name="brand", - ) -] -# Set some facets options -# Assign facet options after creating the object -facets_with_options[0].options = FacetOptions() -# Return the top 3 brands with most items count: -facets_with_options[0].options.page_size = 3 -facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC -facets_with_options[0].options.start = 0 -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_options).execute() -) -`} - - - - -{`# Return the top 3 brands with most items count: -facet_options = FacetOptions() -facet_options.start = 0 -facet_options.page_size = 3 -facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC - -results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the facets options - .with_options(facet_options) - ).execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """from index 'Cameras/ByFeatures' - select facet(brand, $p0)""", - object_type=Camera, - ) - # Add the facet options to the "p0" parameter - .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(Brand, $p0) -{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} -`} - - - -#### Query results: - - - -{`# The resulting items will contain: -# ================================= -# For the "brand" Facet: -# "fuji" - Count: 4 -# "nikon" - Count: 3 -# "olympus" - Count: 2 -# As requested, only 3 unique items are returned, ordered by documents count descending: -`} - - - - -{`# Get facets results for index-field 'brand': -# =========================================== -brand_facets = results["brand"] -number_of_brands = len(brand_facets.values) # 3 brands - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property -# Note: value is lower-case since the default RavenDB analyzer was used by the index -self.assertEqual("fuji", facet_value.range_) -# Number of documents for 'Fuji' is available in the 'Count' property -self.assertEqual(4, facet_value.count_) -`} - - - - - -## Facets - Aggregations - -#### Facets definition: - -* Aggregation of data is available for an index-field per unique Facet or Range item. - For example: - * Get the total number of UnitsInStock per Brand - * Get the highest MegaPixels value for documents that cost between 200 & 400 - -* The following aggregation operations are available: - * Sum - * Average - * Min - * Max - -* Multiple operations can be added on each facet, for multiple fields. - - - -{`# Define the list of facets to query by: -# ===================================== - -# Define a facet: -# =============== -facet_with_aggregations = Facet() -facet_with_aggregations.field_name = "brand" -facet_with_aggregations.aggregations = \{ - # Set the aggregation operation: - FacetAggregation.SUM: - # Create a set specifying the index-fields for which to perform the aggregation - \{ - # Get total number of units_in_stock per brand - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price per brand - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels per brand - FacetAggregationField("mega_pixels"), - # Get max max_focal_length per brand - FacetAggregationField("max_focal_length"), - \}, -\} - -# Define a RangeFacet: -# =================== -range_facet_with_aggregations = RangeFacet() -range_facet_with_aggregations.ranges = [ - "price < 200", - "price between 200 and 400", - "price between 400 and 600", - "price between 600 and 800", - "price >= 800", -] -range_facet_with_aggregations.aggregations = \{ - FacetAggregation.SUM: \{ - # Get total number of units_in_stock for each group of documents per range specified - FacetAggregationField("units_in_stock") - \}, - FacetAggregation.AVERAGE: \{ - # Get average price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MIN: \{ - # Get min price of each group of documents per range specified - FacetAggregationField("price") - \}, - FacetAggregation.MAX: \{ - # Get max mega_pixels for each group of documents per range specified - FacetAggregationField("mega_pixels"), - # Get max max_focal_length for each group of documents per range specified - FacetAggregationField("max_focal_length"), - \}, -\} - -facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] -`} - - -#### Query the index for facets results: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by_facets' to aggregate the data by facets - # Pass the defined facets from above - .aggregate_by_facets(facets_with_aggregations).execute() -) -`} - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_by' to aggregate the data by facets - # Use a builder as follows: - .aggregate_by( - lambda builder: builder - # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM - .by_field("brand") - # Specify the aggregations per the brand facet: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .and_aggregate_by( - lambda builder: builder - # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE - .by_ranges( - RangeBuilder("price").is_less_than(200), - RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), - RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), - RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), - RangeBuilder("price").is_greater_than_or_equal_to(800), - ) - # Specify the aggregations per the price range: - .sum_on("units_in_stock") - .average_on("price") - .min_on("price") - .max_on("mega_pixels") - .max_on("max_focal_length") - ) - .execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query( - """ - from index 'Cameras/ByFeatures' - select - facet(brand, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)), - facet(price < $p0, - price >= $p1 and price < $p2, - price >= $p3 and price < $p4, - price >= $p5 and price < $p6, - price >= $p7, - sum(units_in_stock), - avg(price), - min(price), - max(mega_pixels), - max(max_focal_length)) - """ - ) - .add_parameter("p0", 200.0) - .add_parameter("p1", 200.0) - .add_parameter("p2", 400.0) - .add_parameter("p3", 400.0) - .add_parameter("p4", 600.0) - .add_parameter("p5", 600.0) - .add_parameter("p6", 800.0) - .add_parameter("p7", 800.0) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select - facet(Brand, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)), - facet(Price < $p0, - Price >= $p1 and Price < $p2, - Price >= $p3 and Price < $p4, - Price >= $p5 and Price < $p6, - Price >= $p7, - sum(UnitsInStock), - avg(Price), - min(Price), - max(MegaPixels), - max(MaxFocalLength)) -{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} -`} - - - -#### Query results: - - - -{`# The resulting items will contain (Showing partial results): -# =========================================================== - -# For the "brand" Facet: -# "canon" Count:1, Sum: 30, Name: UnitsInStock -# "canon" Count:1, Min: 200, Average: 200, Name: Price -# "canon" Count:1, Max: 30.4, Name: MegaPixels -# "canon" Count:1, Max: 400, Name: MaxFocalLength - -# "fuji" Count:4, Sum: 42, Name: UnitsInStock -# "fuji" Count:4, Min: 410, Name: Price -# "fuji" Count:4, Max: 102, Name: MegaPixels -# "fuji" Count:4, Max: 800, Name: MaxFocalLength - -# etc..... -# -# For the "Price" Ranges: -# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock -# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price -# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels -# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength - -# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock -# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price -# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels -# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength - -# etc..... -`} - - - - -{`# Get results for the 'brand' facets: -# ======================================== -brand_facets = results["brand"] - -# Get the aggregated facet value for a specific brand: -facet_value = brand_facets.values[0] -# The brand name is available in the 'Range' property: -self.assertEqual("canon", facet_value.range_) -# The index-field on which aggregation was done is in the 'name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result -self.assertEqual(30, facet_value.sum_) - -# Get results for the 'price' RangeFacets: -# ======================================== -price_range_facets = results["price"] - -# Get the aggregated facet value for a specific brand: -facet_value = price_range_facets.values[0] -# The range string is available in the 'Range' property: -self.assertEqual("price < 200", facet_value.range_) -# The index-field on which aggregation was done is in the 'Name' property: -self.assertEqual("units_in_stock", facet_value.name) -# The requested aggregation result: -self.assertEqual(17, facet_value.sum_) -`} - - - - - -## Storing facets definition in a document - -#### Define and store facets in a document: - -* The facets definitions can be stored in a document. - -* That document can then be used by a faceted search query. - - - -{`facet_setup = FacetSetup() -# Provide the ID of the document in which the facet setup will be stored. -# This is optional - -# if not provided then the session will assign an ID for the stored document. -facet_setup.Id = "customDocumentID" - -# Define Facets and RangeFacets to query by: -facet = Facet("brand") -range_facet = RangeFacet() -range_facet.ranges = [ - "mega_pixels < 20", - "mega_pixels between 20 and 30", - "mega_pixels between 30 and 50", - "mega_pixels >= 50", -] - -facet_setup.facets = [facet] -facet_setup.range_facets = [range_facet] - -# Store the facet setup document and save changes: -# =============================================== -session.store(facet_setup) -session.save_changes() - -# The document will be stored under the 'FacetSetups' collection -`} - - -#### Query using facets from document: - - - - -{`results = ( - session - # Query the index - .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) - # Call 'aggregate_using' - # Pass the ID of the document that contains your facets setup - .aggregate_using("customDocumentID").execute() -) -`} - - - - -{`results = ( - session.advanced - # Query the index - # Provide the RQL string to the raw_query method - .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) - # Execute the query - .execute_aggregation() -) -`} - - - - -{`from index "Cameras/ByFeatures" -select facet(id("customDocumentID")) -`} - - - - - - -## Syntax - - - -{`def aggregate_by( - self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] -) -> AggregationDocumentQuery[_T]: ... - -def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... - -def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------------------|----------------------------|-----------------------| -| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | -| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | -| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | - - - - -{`class Facet(FacetBase): - def __init__(self, field_name: str = None): - super().__init__() - self.field_name = field_name -`} - - - - -{`class RangeFacet(FacetBase): - def __init__(self, parent: Optional[FacetBase] = None): - super().__init__() - self.ranges: List[str] = [] -`} - - - - -{`class FacetBase(ABC): - def __init__(self): - self.display_field_name: Union[None, str] = None - self.options: Union[None, FacetOptions] = None - self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} -`} - - - - -{`class FacetAggregation(enum.Enum): - NONE = "None" - MAX = "Max" - MIN = "Min" - AVERAGE = "Average" - SUM = "Sum" -`} - - - - -**Fluent API builder methods**: - - - -{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... - -def by_field(self, field_name: str) -> FacetOperations[_T]: ... - -def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... - -def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... - -def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... - -def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... -`} - - - -| Parameter | Type | Description | -|------------------|-----------------------------|-------------| -| **range_** | `RangeBuilder` | A range of indexes | -| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | -| **field_name** | `str` | The index-field to use for the facet | -| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | -| **display_name** | `str` | If set, results of a facet will be returned under this name | -| **options** | `FacetOptions` | Non-default options to use in the facet definition | - - - -**Options**: - - - -{`class FacetOptions: - def __init__(self): - self.page_size: int = constants.int_max - self.start: Union[None, int] = None - self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC - self.include_remaining_terms: bool = False -`} - - - -| Option | Type | Description | -|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| -| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | -| **start** | `int` | The position from which to send items (how many to skip) | -| **page_size** | `int` | Number of items to return | -| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_paging-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/_paging-csharp.mdx deleted file mode 100644 index 7bba94c71c..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_paging-csharp.mdx +++ /dev/null @@ -1,783 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -List allResults = session - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple query without paging: -// ============================== - -List allResults = await asyncSession - .Query() - .Where(x => x.UnitsInStock > 10) - .OfType() - .ToListAsync(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -List allResults = session.Advanced - .DocumentQuery() - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - .ToList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = await asyncSession - .Query() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToListAsync(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -List thirdPageResults = session.Advanced - .DocumentQuery() - // Get the query stats if you wish to know the TOTAL number of results - .Statistics(out QueryStatistics stats) - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .Skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .Take(10) - .ToList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -long totalResults = stats.TotalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - // Apply some filtering condition as needed - .Where(x => x.UnitsInStock > 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToListAsync(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -List pagedResults; -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - // Apply some filtering condition as needed - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Skip the number of results that were already fetched - .Skip(pageNumber * pageSize) - // Request to get 'pageSize' results - .Take(pageSize) - .ToList(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.Count > 0); // Fetch next results -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - // Define how many items to return - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .Where(x => x.UnitsInStock > 10) - .OfType() - // Define a projection - .Select(x => new ProjectedClass - { - Category = x.Category, - Supplier = x.Supplier - }) - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 10; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .WhereGreaterThan(x => x.UnitsInStock, 10) - .OfType() - // Define a projection - .SelectFields() - // Call Distinct to remove duplicate projected results - .Distinct() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`public class Products_ByUnitsInStock : AbstractIndexCreationTask -{ - public class IndexEntry - { - public int UnitsInStock { get; set; } - } - - public Products_ByUnitsInStock() - { - Map = products => from product in products - select new - { - UnitsInStock = product.UnitsInStock - }; - } -} -`} - - - - -{`public class ProjectedClass -{ - public string Category { get; set; } - public string Supplier { get; set; } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = await asyncSession - .Query() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToListAsync(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`List pagedResults; - -long totalResults = 0; -long skippedResults = 0; -int totalUniqueResults = 0; - -int pageNumber = 0; -int pageSize = 50; - -do -{ - pagedResults = session.Advanced - .DocumentQuery() - .Statistics(out QueryStatistics stats) - .OfType() - // Add the number of skipped results to the "start location" - .Skip((pageNumber * pageSize) + skippedResults) - .Take(pageSize) - .ToList(); - - totalResults = stats.TotalResults; - skippedResults += stats.SkippedResults; - totalUniqueResults += pagedResults.Count; - - pageNumber++; -} -while (pagedResults.Count > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -public class Orders_ByProductName : AbstractIndexCreationTask -{ - public class IndexEntry - { - public string ProductName { get; set; } - } - - public Orders_ByProductName() - { - Map = orders => - from order in orders - from line in order.Lines - select new IndexEntry - { - ProductName = line.ProductName - }; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_paging-java.mdx b/versioned_docs/version-7.1/indexes/querying/_paging-java.mdx deleted file mode 100644 index c69b33f0d7..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_paging-java.mdx +++ /dev/null @@ -1,307 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - -The queries below will return all the results available. - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .toList(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Basic paging: - -Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: - - - - -{`List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) // skip 2 pages worth of products - .take(10) // take up to 10 products - .toList(); // execute query -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Find total results count when paging: - -While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: - - - - -{`Reference stats = new Reference(); - -List results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .whereGreaterThan("UnitsInStock", 10) - .skip(20) - .take(10) - .toList(); - -int totalResults = stats.value.getTotalResults(); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - - -While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `TotalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `SkippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `TotalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `SkippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + SkippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 10; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - - results = session - .query(Product.class, Products_ByUnitsInStock.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .whereGreaterThan("UnitsInStock", 10) - .distinct() - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { - public Products_ByUnitsInStock() { - map = "docs.Products.Select(product => new {" + - " UnitsInStock = product.UnitsInStock" + - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct * -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`List results; -int pageNumber = 0; -int pageSize = 50; -int skippedResults = 0; -Reference stats = new Reference<>(); - -do { - results = session - .query(Order.class, Order_ByOrderLines_ProductName.class) - .statistics(stats) - .skip((pageNumber * pageSize) + skippedResults) - .take(pageSize) - .toList(); - - skippedResults += stats.value.getSkippedResults(); - pageNumber++; -} while (results.size() > 0); -`} - - - - -{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { - public Orders_ByOrderLines_ProductName() { - map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + - " Product = line.ProductName " + - "})"; - } -} -`} - - - - -{`from index "Order/ByOrderLines/ProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_paging-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/_paging-nodejs.mdx deleted file mode 100644 index 253f2a5e98..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_paging-nodejs.mdx +++ /dev/null @@ -1,400 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). - In such case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -const allResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .whereGreaterThan("UnitsInStock", 10) - .all(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -// Define an output param for getting the query stats -let stats; - -const thirdPageResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Get the query stats if you wish to know the TOTAL number of results - .statistics(s => stats = s) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - .skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - .take(10) - .all(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -const totalResults = stats.totalResults; - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -const PAGE_SIZE = 10; -let pageNumber = 0; -let pagedResults; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - // Apply some filtering condition as needed - .whereGreaterThan("UnitsInStock", 10) - // Skip the number of results that were already fetched - .skip(pageNumber * PAGE_SIZE) - // Request to get 'pageSize' results - .take(PAGE_SIZE) - .all(); - - pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (pagedResults.length > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance -**Better performance**: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -**Performance hints**: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - -![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In those cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* In order to do proper paging in those scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 10; - -do { - pagedResults = await session - .query({ indexName: "Products/ByUnitsInStock" }) - .statistics(s => stats = s) - .whereGreaterThan("UnitsInStock", 10) - // Define a projection - .selectFields(["Category", "Supplier"]) - // Call Distinct to remove duplicate projected results - .distinct() - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - // Define how many items to return - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) - skippedResults += stats.skippedResults; // Number of duplicate results that were skipped - totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to skip(). -`} - - - - -{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Products", p => ({ - UnitsInStock: p.UnitsInStock - })); - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`let pagedResults; -let stats; - -let totalResults = 0; -let totalUniqueResults = 0; -let skippedResults = 0; - -let pageNumber = 0; -const PAGE_SIZE = 50; - -do { - pagedResults = await session - .query({ indexName: "Orders/ByProductName" }) - .statistics(s => stats = s) - // Add the number of skipped results to the "start location" - .skip((pageNumber * PAGE_SIZE) + skippedResults) - .take(PAGE_SIZE) - .all(); - - totalResults = stats.totalResults; - skippedResults += stats.skippedResults; - totalUniqueResults += pagedResults.length; - - pageNumber++; -} -while (pagedResults.length > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Orders", order => { - return order.Lines.map(line => { - return { - ProductName: line.ProductName - }; - }); - }); - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_paging-php.mdx b/versioned_docs/version-7.1/indexes/querying/_paging-php.mdx deleted file mode 100644 index 596a8e12fd..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_paging-php.mdx +++ /dev/null @@ -1,688 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`// A simple query without paging: -// ============================== - -/** @var array $allResults */ -$allResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`// A simple DocumentQuery without paging: -// ====================================== - -/** @var array $allResults */ -$allResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - ->toList(); - -// Executing the query on the Northwind sample data -// will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats ) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`// Retrieve only the 3'rd page - when page size is 10: -// =================================================== - -$stats = new QueryStatistics(); - -/** @var array $thirdPageResults */ -$thirdPageResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Get the query stats if you wish to know the TOTAL number of results - ->statistics($stats) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Call 'Skip', pass the number of items to skip from the beginning of the result set - // Skip the first 20 resulting documents - ->skip(20) - // Call 'Take' to define the number of documents to return - // Take up to 10 products => so 10 is the "Page Size" - ->take(10) - ->toList(); - -// When executing this query on the Northwind sample data, -// results will include only 10 Product documents ("products/45-A" to "products/54-A") - -$totalResults = $stats->getTotalResults(); - -// While the query returns only 10 results, -// \`totalResults\` will hold the total number of matching documents (47). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`// Query for all results - page by page: -// ===================================== - -$pagedResults = null; -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - // Apply some filtering condition as needed - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Skip the number of results that were already fetched - ->skip($pageNumber * $pageSize) - // Request to get 'pageSize' results - ->take($pageSize) - ->toList(); - - $pageNumber++; - - // Make any processing needed with the current paged results here - // ... -} -while (count($pagedResults) > 0); // Fetch next results -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `totalResults` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skippedResults` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. - - * The `totalResults` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skippedResults` value when specifying the number of documents to skip for each page using: - `(currentPage * pageSize) + skippedResults`. - -## Examples - -#### A projection query with Distinct: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session - ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - // Define how many items to return - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 10; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) - ->statistics($stats) - ->whereGreaterThan("UnitsInStock", 10) - ->ofType(Product::class) - // Define a projection - ->selectFields(ProjectedClass::class) - // Call Distinct to remove duplicate projected results - ->distinct() - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) - $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped - $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total matching results reported in the stats is 47 (totalResults), -// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -// due to the 'Distinct' usage which removes duplicates. - -// This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock_IndexEntry -{ - private ?int $unitsInStock = null; - - public function getUnitsInStock(): ?int - { - return $this->unitsInStock; - } - - public function setUnitsInStock(?int $unitsInStock): void - { - $this->unitsInStock = $unitsInStock; - } -} - -class Products_ByUnitsInStock extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Products.Select(product => new {" . - " UnitsInStock = product.UnitsInStock" . - "})"; - } -} -`} - - - - -{`class ProjectedClass -{ - public ?string $category = null; - public ?string $supplier = null; - - public function getCategory(): ?string - { - return $this->category; - } - - public function setCategory(?string $category): void - { - $this->category = $category; - } - - public function getSupplier(): ?string - { - return $this->supplier; - } - - public function setSupplier(?string $supplier): void - { - $this->supplier = $supplier; - } -} -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session - ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`$pagedResults = null; - -$totalResults = 0; -$totalUniqueResults = 0; -$skippedResults = 0; - -$pageNumber = 0; -$pageSize = 50; - -do -{ - $pagedResults = $session->advanced() - ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) - ->statistics($stats) - ->ofType(Order::class) - // Add the number of skipped results to the "start location" - ->skip(($pageNumber * $pageSize) + $skippedResults) - ->take($pageSize) - ->toList(); - - $totalResults = $stats->getTotalResults(); - $skippedResults += $stats->getSkippedResults(); - $totalUniqueResults += count($pagedResults); - - $pageNumber++; -} -while (count($pagedResults) > 0); // Fetch next results - -// When executing the query on the Northwind sample data: -// ====================================================== - -// The total results reported in the stats is 2155 (totalResults), -// which represent the multiple index-entries generated as defined by the fanout index. - -// By adding the skipped results count to the Skip() method, -// we get the correct total unique results which is 830 Order documents. -`} - - - - -{`// A fanout index - creating MULTIPLE index-entries per document: -// ============================================================== - -class Orders_ByProductName_IndexEntry -{ - private ?string $productName = null; - - public function getProductName(): ?string - { - return $this->productName; - } - - public function setProductName(?string $productName): void - { - $this->productName = $productName; - } -} -class Orders_ByProductName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . - " Product = line.ProductName " . - "})"; - } -} -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_paging-python.mdx b/versioned_docs/version-7.1/indexes/querying/_paging-python.mdx deleted file mode 100644 index 3ca064b801..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_paging-python.mdx +++ /dev/null @@ -1,431 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* **Paging**: - Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. - This method enables processing query results one page at a time. - -* **Default page size**: - - * Querying **Lucene** indexes: - If the client's query definition does Not explicitly specify the page size, - the server will default to a C# `int.MaxValue` (2,147,483,647). - In such a case, all results will be returned in a single server call. - - * Querying **Corax** indexes: - The default page size is the same as the one employed by Lucene. - Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, - indexes with more than a C# `int.MaxValue` entries can be created and used. - To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. - -* **Performance**: - Using paging is beneficial when handling large result datasets, contributing to improved performance. - See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. - -* In this page: - - * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) - * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) - * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) - * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) - - -## No-paging example - - - - -{`# A simple query without paging: -# ============================== -all_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .where_greater_than("units_in_stock", 10) - .of_type(Product) -) - -# Executing the query on the Northwind sample data -# will result in all 47 Product documents that match the query predicate. -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -`} - - - - - - -## Paging examples - -#### Retrieve a specific page: - - - - -{`# Retrieve only the 3'rd page - when page size is 10: -# =================================================== -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - # While the query below returns only 10 results, - # 'total_results' will hold the total number of matching documents (47). - -third_page_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Get the query stats if you wish to know the TOTAL number of results - .statistics(__stats_callback) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Call 'skip', pass the number of items to skip from the beginning of the result set - # Skip the first 20 resulting documents - .skip(20) - # Call 'take' to define the number of documents to return - # Take up to 10 products => so 10 is the "Page Size" - .take(10) -) - -en executing this query on the Northwind sample data, -sults will include only 10 Product documents ("products/45-A" to "products/54-A") - - store.open_session() as session: -# region paging_2_1 -# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 20, 10 // skip 20, take 10 -`} - - - -#### Page through all results: - - - - -{`# Query for all results - page by page: -# ===================================== -paged_results: List[Product] = [] -page_number = 0 -page_size = 10 - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - # Apply some filtering condition as needed - .where_greater_than("units_in_stock", 10).of_type(Product) - # Skip the number of results that were already fetched - .skip(page_number * page_size) - # Request to get 'page_size' results - .take(page_size) - ) - page_number += 1 - - if len(paged_results) == 0: - break - - # Make any processing needed with the current paged results here - # ... -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -limit 0, 10 // First loop will skip 0, take 10 - -// The next loops in the code will each generate the above RQL with an increased 'skip' value: -// limit 10, 10 -// limit 20, 10 -// limit 30, 10 -// ... -`} - - - - - - -## Paging and performance - -#### Better performance: - -It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. -This practice has several benefits: - -* Optimizes bandwidth usage by reducing data transfer between the server and client. -* Prevents delays in response times caused by sending too much data over the network. -* Avoids high memory consumption when dealing with numerous documents. -* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. -#### Performance hints: - -* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. - -* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. - -* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. - - ![Figure 1. Performance Hint](./assets/performance-hint.png) - - - -## Paging through tampered results - -* The `QueryStatistics` object contains the `total_results` property, - which represents the total number of matching documents found in the query results. - -* The `QueryStatistics` object also contains the `skipped_results` property. - Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. - -* The server will skip duplicate results internally in the following two scenarios: - - 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). - - 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). - -* In these cases: - - * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. - - * The `total_results` property will be invalidated - - it will Not deduct the number of skipped results from the total number of results. - -* To do proper paging in these scenarios: - include the `skipped_results` value when specifying the number of documents to skip for each page using: - `(current_page * page_size) + skipped_results`. - -## Examples - -#### A projection query with Distinct: - - - - -{`paged_results: List[ProjectedClass] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 10 - -def __stats_callback(statistics: QueryStatistics): - total_results = statistics.total_results - nonlocal skipped_results - skipped_results += statistics.skipped_results - -while True: - paged_results = list( - session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) - .statistics(__stats_callback) - .where_greater_than("units_in_stock", 10) - .of_type(Product) - # Define a projection - .select_fields(ProjectedClass) - # Call distinct to remove duplicate projected results - .distinct() - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total matching results reported in the stats is 47 (totalResults), -# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) -# due to the 'Distinct' usage which removes duplicates. - -# This is solved by adding the skipped results count to Skip(). -`} - - - - -{`class Products_ByUnitsInStock(AbstractIndexCreationTask): - def __init__(self): - super().__init__() - self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" - - class IndexEntry: - def __init__(self, units_in_stock: int = None): - self.units_in_stock = units_in_stock -`} - - - - -{`class ProjectedClass: - def __init__(self, category: str = None, supplier: str = None): - self.category = category - self.supplier = supplier - - # Handle different casing by implementing from_json class method - @classmethod - def from_json(cls, json_dict: Dict[str, Any]): - return cls(json_dict["Category"], json_dict["Supplier"]) -`} - - - - -{`from index "Products/ByUnitsInStock" -where UnitsInStock > 10 -select distinct Category, Supplier -limit 0, 10 // First loop will skip 0, take 10, etc. -`} - - - - -#### Querying a Fanout index: - - - - -{`paged_results: List[Order] = [] - -total_results = 0 -total_unique_results = 0 -skipped_results = 0 - -page_number = 0 -page_size = 50 - -def __stats_callback(statistics: QueryStatistics): - nonlocal skipped_results - skipped_results += statistics.skipped_results - total_results = statistics.total_results - -while True: - paged_results = list( - session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) - .statistics(__stats_callback) - .of_type(Order) - # Add the number of skipped results to the "start location" - .skip((page_size * page_size) + skipped_results) - .take(page_size) - ) - - total_unique_results += len(paged_results) - - if len(paged_results) == 0: - break - -# When executing the query on the Northwind sample data: -# ====================================================== - -# The total results reported in the stats is 2155 (total_results), -# which represent the multiple index-entries generated as defined by the fanout index. - -# By adding the skipped results count to the skip() method, -# we get the correct total unique results which is 830 Order documents. -`} - - - - -{`# A fanout index - creating MULTIPLE index-entries per document: -# ============================================================== -class Orders_ByProductName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" -`} - - - - -{`from index "Orders/ByProductName" -limit 0, 50 // First loop will skip 0, take 50, etc. -`} - - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_spatial-java.mdx b/versioned_docs/version-7.1/indexes/querying/_spatial-java.mdx deleted file mode 100644 index b3e21d4a8e..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_spatial-java.mdx +++ /dev/null @@ -1,121 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. -You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Radius Search - -The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) -`} - - - - -## Advanced Search - -The most advanced (and low-level) method available is `relatesToShape` - - - - -{`List results = session - .query(Event.class) - .spatial(new PointField("latitude", "longitude"), - criteria -> criteria.relatesToShape( - "Circle(30 30 d=500.0000)", - SpatialRelation.WITHIN - )) - .toList(); -`} - - - - -{`from Events -where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) -`} - - - - -Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. - - -When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed -in a counter-clockwise order: - - - -![NoSQL ACID DB - Query a Spatial Index](./assets/spatial_1.png) - - -## Static Indexes - -All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. - - - - -{`List results = session - .query(Event.class, Events_ByCoordinates.class) - .spatial("coordinates", - criteria -> criteria.withinRadius(500, 30, 30)) - .toList(); -`} - - - - -{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { - public Events_ByCoordinates() { - map = "docs.Events.Select(e => new {" + - " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + - "})"; - } -} -`} - - - - -{`from index 'Events/ByCoordinates' -where spatial.within(coordinates, spatial.circle(500, 30, 30)) -`} - - - - - -If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. - - -## Ordering - -In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). - -## Remarks - - -Distance in RavenDB by default is measured in **kilometers**. - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_suggestions-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/_suggestions-csharp.mdx deleted file mode 100644 index f2c63f193d..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_suggestions-csharp.mdx +++ /dev/null @@ -1,608 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`public class Products_ByName : AbstractIndexCreationTask -\{ - // The IndexEntry class defines the index-fields - public class IndexEntry - \{ - public string ProductName \{ get; set; \} - \} - - public Products_ByName() - \{ - // The 'Map' function defines the content of the index-fields - Map = products => from product in products - select new IndexEntry - \{ - ProductName = product.Name - \}; - - // Configure index-field 'ProductName' for suggestions - Suggestion(x => x.ProductName); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - Indexes.Add(x => x.ProductName, FieldIndexing.Search); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -List products = session - .Query() - .Search(x => x.ProductName, "chokolade") - .OfType() - .ToList(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for single term -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .ByField(x => x.ProductName, "chokolade")) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request for multiple terms -var suggestionRequest = new SuggestionWithTerms("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - Terms = new[] { "chokolade", "syrop"} -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) - .Execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .ExecuteAsync(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -var request1 = new SuggestionWithTerm("CompanyName") -{ - // Looking for terms from index-field 'CompanyName' that are similar to 'chese' - Term = "chese" -}; - -var request2 = new SuggestionWithTerm("ContactName") -{ - // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' - Term = "frank" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - .SuggestUsing(request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - .AndSuggestUsing(request2) - .Execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .SuggestUsing(builder => builder - .ByField(x => x.CompanyName, "chese" )) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .AndSuggestUsing(builder => builder - .ByField(x => x.ContactName, "frank")) - .Execute(); -`} - - - - -{`public class Companies_ByNameAndByContactName : - AbstractIndexCreationTask -{ - // The IndexEntry class defines the index-fields. - public class IndexEntry - { - public string CompanyName { get; set; } - public string ContactName { get; set; } - } - - public Companies_ByNameAndByContactName() - { - // The 'Map' function defines the content of the index-fields - Map = companies => from company in companies - select new IndexEntry - { - CompanyName = company.Name, - ContactName = company.Contact.Name - }; - - // Configure the index-fields for suggestions - Suggestion(x => x.CompanyName); - Suggestion(x => x.ContactName); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - Indexes.Add(x => x.CompanyName, FieldIndexing.Search); - Indexes.Add(x => x.ContactName, FieldIndexing.Search); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = await asyncSession - // Query the index - .Query() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .ExecuteAsync(); -`} - - - - -{`// Define the suggestion request -var suggestionRequest = new SuggestionWithTerm("ProductName") -{ - // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' - Term = "chokolade", - // Customize options - Options = new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }, - // Customize display name - DisplayField = "SomeCustomName" -}; - -// Query the index for suggestions -Dictionary suggestions = session - .Query() - // Call 'SuggestUsing' - pass the suggestion request - .SuggestUsing(suggestionRequest) - .Execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -Dictionary suggestions = session.Advanced - // Query the index - .DocumentQuery() - // Call 'SuggestUsing' - .SuggestUsing(builder => builder - .ByField(x => x.ProductName, "chokolade") - // Customize suggestions options - .WithOptions(new SuggestionOptions - { - Accuracy = 0.3f, - PageSize = 5, - Distance = StringDistanceTypes.NGram, - SortMode = SuggestionSortMode.Popularity - }) - // Customize display name for results - .WithDisplayName("SomeCustomName")) - .Execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -Console.WriteLine("Suggested terms:"); -// Results are available under the custom name entry -foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) -\{ - Console.WriteLine("\\t\{0\}", suggestedTerm); -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_suggestions-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/_suggestions-nodejs.mdx deleted file mode 100644 index 5b2d2f4fec..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_suggestions-nodejs.mdx +++ /dev/null @@ -1,341 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ - constructor() \{ - super(); - - this.map("Products", p => \{ - return \{ - ProductName: p.Name - \}; - \}); - - // Configure index-field 'ProductName' for suggestions - this.suggestion("ProductName"); - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - this.index("ProductName", "Search"); - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the **Northwind sample data**, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the **Northwind sample data**, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -const products = await session - .query(\{ indexName: "Products/ByName" \}) - .search("ProductName", "chokolade") - .all(); -`} - - - -If you suspect that the term `chokolate` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .byField("ProductName", "chokolade")) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); -suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - .byField("ProductName", ["chokolade", "syrop"])) - .execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Companies/ByNameAndByContactName" }) - // Call 'suggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - .suggestUsing(x => x.byField("CompanyName", "chese")) - // Call 'andSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - .andSuggestUsing(x => x.byField("ContactName", "frank")) - .execute(); -`} - - - - -{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { - constructor() { - super(); - - this.map("Companies", p => { - return { - CompanyName: p.Name, - ContactName: p.Contact.Name - }; - }); - - // Configure the index-fields for suggestions - this.suggestion("CompanyName"); - this.suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - this.index("CompanyName", "Search"); - this.index("ContactName", "Search"); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -const suggestions = await session - // Query the index - .query({ indexName: "Products/ByName" }) - // Call 'suggestUsing' - .suggestUsing(x => x - .byField("ProductName", "chokolade") - // Customize suggestions options - .withOptions({ - accuracy: 0.3, - pageSize: 5, - distance: "NGram", - sortMode: "Popularity" - }) - // Customize display name for results - .withDisplayName("SomeCustomName")) - .execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -console.log("Suggested terms:"); -// Results are available under the custom name entry -suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ - console.log("\\t" + suggestedTerm); -\}); - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_suggestions-php.mdx b/versioned_docs/version-7.1/indexes/querying/_suggestions-php.mdx deleted file mode 100644 index bbfa5951fd..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_suggestions-php.mdx +++ /dev/null @@ -1,585 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`// The IndexEntry class defines the index-fields -class Products_ByName_IndexEntry -\{ - private ?string $productName = null; - - public function getProductName(): ?string - \{ - return $this->productName; - \} - - public function setProductName(?string $productName): void - \{ - $this->productName = $productName; - \} -\} -class Products_ByName extends AbstractIndexCreationTask -\{ - public function __construct() - \{ - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map = "from product in docs.Products " . - "select new " . - "\{ " . - " product.Name " . - "\} "; - - // Configure index-field 'ProductName' for suggestions - $this->suggestion("Name"); // configuring suggestions - - // Optionally: set 'Search' on this field - // This will split the field content into multiple terms allowing for a full-text search - $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens - - \} -\} -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`// This query on index 'Products/ByName' has NO resulting documents -/** @var array $products */ -$products = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - ->search("ProductName", "chokolade") - ->ofType(Product::class) - ->toList(); -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function ($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for single term -$suggestionRequest = new SuggestionWithTerm("ProductName"); -$suggestionRequest->setTerm("chokolade"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->Execute(); -`} - - - - -{`// Query the index for suggested terms for single term: -// ==================================================== - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - return $builder->byField("ProductName", "chokolade"); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; -foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': -// schokolade -// chocolade -// chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->ByField("ProductName", ["chokolade", "syrop"]); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request for multiple terms -$suggestionRequest = new SuggestionWithTerms("ProductName"); -$suggestionRequest->setTerms([ "chokolade", "syrop" ]); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms for multiple terms: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - return $builder - // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' - ->byField("ProductName", [ "chokolade", "syrop" ]); - }) - ->execute(); -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': -// schokolade -// chocolade -// chocolate -// sirop -// syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->byField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(functioN($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// Define suggestion requests for multiple fields: - -$request1 = new SuggestionWithTerm("CompanyName"); -// Looking for terms from index-field 'CompanyName' that are similar to 'chese' -$request1->setTerm("chese"); - -$request2 = new SuggestionWithTerm("ContactName"); -// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' -$request2->setTerm("frank"); - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' - pass the suggestion request for the first index-field - ->suggestUsing($request1) - // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field - ->andSuggestUsing($request2) - ->execute(); -`} - - - - -{`// Query the index for suggested terms in multiple fields: -// ======================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) - // Call 'SuggestUsing' to get suggestions for terms that are - // similar to 'chese' in first index-field (e.g. 'CompanyName') - ->suggestUsing(function($builder) { - return $builder - ->ByField("CompanyName", "chese" ); - }) - // Call 'AndSuggestUsing' to get suggestions for terms that are - // similar to 'frank' in an additional index-field (e.g. 'ContactName') - ->andSuggestUsing(function($builder) { - return $builder - ->byField("ContactName", "frank"); - }) - ->execute(); -`} - - - - -{`// The IndexEntry class defines the index-fields. -class Companies_ByNameAndByContactName_IndexEntry -{ - private ?string $companyName = null; - private ?string $contactName = null; - - public function getCompanyName(): ?string - { - return $this->companyName; - } - - public function setCompanyName(?string $companyName): void - { - $this->companyName = $companyName; - } - - public function getContactName(): ?string - { - return $this->contactName; - } - - public function setContactName(?string $contactName): void - { - $this->contactName = $contactName; - } -} - -class Companies_ByNameAndByContactName extends AbstractIndexCreationTask -{ - public function __construct() - { - parent::__construct(); - - // The 'Map' function defines the content of the index-fields - $this->map= "from company in docs.Companies" . - "select new { " . - "CompanyName = company.Name, " . - "ContactName = company.Contact.Name " . - "}"; - - // Configure the index-fields for suggestions - $this->suggestion("CompanyName"); - $this->suggestion("ContactName"); - - // Optionally: set 'Search' on the index-fields - // This will split the fields' content into multiple terms allowing for a full-text search - $this->index("CompanyName", FieldIndexing::search()); - $this->index("ContactName", FieldIndexing::search()); - } -} -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -// Suggested terms in index-field 'CompanyName' that is similar to 'chese': -// cheese -// chinese - -// Suggested terms in index-field 'ContactName' that are similar to 'frank': -// fran -// franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session - // Query the index - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $suggestionOptions = new SuggestionOptions(); - $suggestionOptions->setAccuracy(0.3); - $suggestionOptions->setPageSize(5); - $suggestionOptions->setDistance(StringDistanceTypes::nGram()); - $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); - - $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($suggestionOptions) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Define the suggestion request -$suggestionRequest = new SuggestionWithTerm("ProductName"); -// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -$suggestionRequest->setTerm("chokolade"); - -// Customize options -$options = new SuggestionOptions(); -$options->setAccuracy(0.3); -$options->setPageSize(5); -$options->setDistance(StringDistanceTypes::nGram()); -$options->setSortMode(SuggestionSortMode::popularity()); - -$suggestionRequest->setOptions($options); - -// Customize display name -$suggestionRequest->setDisplayField("SomeCustomName"); - - -// Query the index for suggestions -/** @var array $suggestions */ -$suggestions = $session - ->query(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - pass the suggestion request - ->suggestUsing($suggestionRequest) - ->execute(); -`} - - - - -{`// Query the index for suggested terms - customize options and display name: -// ========================================================================= - -/** @var array $suggestions */ -$suggestions = $session->advanced() - // Query the index - ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) - // Call 'SuggestUsing' - ->suggestUsing(function($builder) { - $options = new SuggestionOptions(); - $options->setAccuracy(0.3); - $options->setPageSize(5); - $options->setDistance(StringDistanceTypes::nGram()); - $options->setSortMode(SuggestionSortMode::popularity()); - - return $builder - ->byField("ProductName", "chokolade") - // Customize suggestions options - ->withOptions($options) - // Customize display name for results - ->withDisplayName("SomeCustomName"); - }) - ->execute(); -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`// The resulting suggested terms: -// ============================== - -echo "Suggested terms:"; -// Results are available under the custom name entry -foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) -\{ - echo "\\t" . $suggestedTerm; -\} - -// Suggested terms: -// chocolade -// schokolade -// chocolate -// chowder -// marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_suggestions-python.mdx b/versioned_docs/version-7.1/indexes/querying/_suggestions-python.mdx deleted file mode 100644 index 79cee84018..0000000000 --- a/versioned_docs/version-7.1/indexes/querying/_suggestions-python.mdx +++ /dev/null @@ -1,424 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) - for general knowledge about Suggestions and for dynamic-queries examples. - -* In addition to getting suggested terms when making a dynamic-query, - you can query for similar terms when querying an index. - -* This article provides examples of querying an index for suggestions. - Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). - -* In this page: - * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) - * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) - * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) - * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) - * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) - * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) - - -## Configure the index for suggestions - -* In order to be able to ask for suggested terms when querying an index field, - that field must first be configured for suggestions in the **index definition**. - -* See the following sample index: - (This index will be used in the examples ahead). - - - -{`class Products_ByName(AbstractIndexCreationTask): - # The IndexEntry class defines the index-fields - class IndexEntry: - def __init__(self, product_name: str = None): - self.product_name = product_name - - def __init__(self): - super().__init__() - # The 'map' function defines the content of the index-fields - self.map = "from product in docs.Products select new \{product_name = product.Name\}" - self._suggestion("product_name") - self._index("product_name", FieldIndexing.SEARCH) -`} - - - - - -**Increased indexing time**: - -* When configuring an index for suggestions, then during the indexing process, - in addition to the regular breakdown of the data into terms (tokenization), - RavenDB will scramble the terms to simulate common errors. - -* This can impact indexing speed but the cost of querying suggestions is Not impacted. - - - - - -## The index terms - -Based on the Northwind sample data, -these are the terms generated for the above index `Products/ByName`: - -![Figure 1. Index terms](./assets/index-terms.png) - -1. **The index-field name** - as defined in the index definition. - In this example the field name is `ProductName`. - -2. **The terms** that were generated for this index-field from the documents in the Products collection. - * The image shows a partial view out of the 163 terms in this list. - * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. - - - -## Suggest terms - for a single term - -Based on the Northwind sample data, -the following query on the index `Products/ByName` from above has no resulting documents, -since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. - - - -{`# This query on index 'Products/ByName' has NO resulting documents -products = list( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - .search("product_name", "chokolade") - .of_type(Product) -) -`} - - - -If you suspect that the term `chokolade` in the query criteria is written incorrectly, -you can ask RavenDB to suggest similar terms from the index, as follows: - - - - -{`# Query the index for suggested terms for single term: -# ==================================================== - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' - .by_field("product_name", "chokolade") - ).execute() -) -`} - - - - -{`# Define the suggestion request for single term -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' -suggestion_request.term = "chokolade" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' -from index "Products/ByName" -select suggest(ProductName, "chokolade") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") -for suggested_term in suggestions["product_name"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade': -# schokolade -# chocolade -# chocolate -`} - - - - - -## Suggest terms - for multiple terms - - - - -{`# Query the index for suggested terms for multiple terms: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder - # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' - .by_field("product_name", ["chokolade", "syrop"]) - ).execute() -) -`} - - - - -{`# Define the suggestion request for multiple terms -suggestion_request = SuggestionWithTerms("product_name") -# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' -suggestion_request.terms = ["chokolade", "syrop"] - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' -from index "Products/ByName" select suggest(ProductName, $p0) -{ "p0" : ["chokolade", "syrop"] } -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': -# schokolade -# chocolade -# chocolate -# sirop -# syrup -`} - - - - - -## Suggest terms - for multiple fields - - - - -{`# Query the index for suggested terms in multiple fields: -# ======================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) - # Call 'suggest_using' to get suggestions for terms that are - # similar to 'chese' in first index-field (e.g. 'company_name') - .suggest_using(lambda builder: builder.by_field("company_name", "chese")) - # Call 'and_suggest_using' to get suggestions for terms that are - # similar to 'frank' in an additional index-field (e.g. 'company_name') - .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() -) -`} - - - - -{`# Define suggestion requests for multiple fields: - -request1 = SuggestionWithTerm("company_name") -# Looking for terms from index-field 'company_name' that are similar to 'chese' -request1.term = "chese" - -request2 = SuggestionWithTerm("contact_name") -# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' -request2.term = "frank" - -# Query the index for suggestions -suggestions = ( - session.query_index_type( - Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry - ) - # Call 'suggest_using' - pass the suggestion request for the first index-field - .suggest_using(request1) - # Call 'and_suggest_using' - pass the suggestion request for the second index-field - .and_suggest_using(request2).execute() -) -`} - - - - -{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): - class IndexEntry: - def __init__(self, company_name: str = None, contact_name: str = None): - self.company_name = company_name - self.contact_name = contact_name - - def __init__(self): - super().__init__() - self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" - - # Configure the index-fields for suggestions - self._suggestion("company_name") - self._suggestion("contact_name") - - # Optionally: set 'search' on the index-fields - # This will split the fields' content into multiple terms allowing for a full-text search - self._index("company_name", FieldIndexing.SEARCH) - self._index("contact_name", FieldIndexing.SEARCH) -`} - - - - -{`// Query for suggested terms -// from index-field 'CompanyName' AND from index-field 'ContactName' -from index "Companies/ByNameAndByContactName" -select suggest(CompanyName, "chese"), suggest(ContactName, "frank") -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -# Suggested terms in index-field 'company_name' that is similar to 'chese': -# cheese -# chinese - -# Suggested terms in index-field 'contact_name' that are similar to 'frank': -# fran -# franken -`} - - - - - -## Suggest terms - customize options and display name - - - - -{`# Query the index for suggested terms - customize options and display name: -# ========================================================================= - -suggestions = ( - session - # Query the index - .query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - .suggest_using( - lambda builder: builder.by_field("product_name", "chokolade") - # Customize suggestions options - .with_options( - SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, - ) - ) - # Customize display name for results - .with_display_name("SomeCustomName") - ).execute() -) -`} - - - - -{`# Define the suggestion request -suggestion_request = SuggestionWithTerm("product_name") -# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' -suggestion_request.term = "chokolade" -# Customize options -suggestion_request.options = SuggestionOptions( - accuracy=0.3, - page_size=5, - distance=StringDistanceTypes.N_GRAM, - sort_mode=SuggestionSortMode.POPULARITY, -) -# Customize display name -suggestion_request.display_field = "SomeCustomName" - -# Query the index for suggestions -suggestions = ( - session.query_index_type(Products_ByName, Products_ByName.IndexEntry) - # Call 'suggest_using' - pass the suggestion request - .suggest_using(suggestion_request).execute() -) -`} - - - - -{`// Query for suggested terms - customize options and display name -from index "Products/ByName" -select suggest( - ProductName, - "chokolade", - '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' -) as "SomeCustomName" -`} - - - - - - -{`# The resulting suggested terms: -# ============================== - -print("Suggested terms:") -# Results are available under the custom name entry -for suggested_term in suggestions["SomeCustomName"].suggestions: - print(f"\\t\{suggested_term\}") - -# Suggested terms: -# chocolade -# schokolade -# chocolate -# chowder -# marmalade -`} - - - - - - diff --git a/versioned_docs/version-7.1/indexes/querying/_distinct-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_distinct-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_distinct-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_distinct-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_distinct-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_distinct-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_distinct-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_distinct-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_distinct-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_distinct-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_distinct-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_distinct-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_exploration-queries-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_exploration-queries-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_exploration-queries-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_exploration-queries-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_exploration-queries-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_exploration-queries-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_exploration-queries-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_exploration-queries-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_exploration-queries-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-csharp.mdx new file mode 100644 index 0000000000..7adddea4b9 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-csharp.mdx @@ -0,0 +1,1052 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`public class Camera +{ + public string Manufacturer { get; set; } + public double Cost { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } +} +`} + + + + +{`public class Cameras_ByFeatures : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string Brand { get; set; } + public double Price { get; set; } + public double MegaPixels { get; set; } + public int MaxFocalLength { get; set; } + public int UnitsInStock { get; set; } + } + + public Cameras_ByFeatures() + { + Map = cameras => from camera in cameras + select new + { + Brand = camera.Manufacturer, + Price = camera.Cost, + MegaPixels = camera.MegaPixels, + MaxFocalLength = camera.MaxFocalLength, + UnitsInStock = camera.UnitsInStock + }; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +var cameras = new[] +{ + new Camera { Manufacturer = "Sony", Cost = 100, MegaPixels = 20.1, MaxFocalLength = 200, UnitsInStock = 10 }, + new Camera { Manufacturer = "Sony", Cost = 200, MegaPixels = 29, MaxFocalLength = 250, UnitsInStock = 15 }, + new Camera { Manufacturer = "Nikon", Cost = 120, MegaPixels = 22.3, MaxFocalLength = 300, UnitsInStock = 2 }, + new Camera { Manufacturer = "Nikon", Cost = 180, MegaPixels = 32, MaxFocalLength = 300, UnitsInStock = 5 }, + new Camera { Manufacturer = "Nikon", Cost = 220, MegaPixels = 40, MaxFocalLength = 300, UnitsInStock = 20 }, + new Camera { Manufacturer = "Canon", Cost = 200, MegaPixels = 30.4, MaxFocalLength = 400, UnitsInStock = 30 }, + new Camera { Manufacturer = "Olympus", Cost = 250, MegaPixels = 32.5, MaxFocalLength = 600, UnitsInStock = 4 }, + new Camera { Manufacturer = "Olympus", Cost = 390, MegaPixels = 40, MaxFocalLength = 600, UnitsInStock = 6 }, + new Camera { Manufacturer = "Fuji", Cost = 410, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 1 }, + new Camera { Manufacturer = "Fuji", Cost = 590, MegaPixels = 45, MaxFocalLength = 700, UnitsInStock = 5 }, + new Camera { Manufacturer = "Fuji", Cost = 650, MegaPixels = 61, MaxFocalLength = 800, UnitsInStock = 17 }, + new Camera { Manufacturer = "Fuji", Cost = 850, MegaPixels = 102, MaxFocalLength = 800, UnitsInStock = 19 } +}; + +using (var session = store.OpenSession()) +{ + foreach (var camera in cameras) + { + session.Store(camera); + } + + session.SaveChanges(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +List facets = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + // e.g. get the number of Camera documents for each unique Brand + FieldName = "Brand", + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Brand" + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + // Specify ranges within an index-field in order to get count per RANGE + // e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + // Set a display name for this field in the results (optional) + DisplayFieldName = "Camera Price" + \} +\}; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facets) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Brand")) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Set a display name for the field in the results (optional) + .WithDisplayName("Camera Price")) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dictionary` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +var brandFacets = results["Camera Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("canon", facetValue.Range); +// Number of documents for 'Canon' is available in the 'Count' property +Assert.Equal(1, facetValue.Count); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +var priceFacets = results["Camera Price"]; +var numberOfRanges = priceFacets.Values.Count; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.Values[0]; +Assert.Equal("Price < 200", facetValue.Range); // The range string +Assert.Equal(3, facetValue.Count); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`Dictionary filteredResults = session + .Query() + // Limit query results to the selected brands: + .Where(x => x.Brand.In("Fuji", "Nikon")) + .AggregateBy(facets) + .Execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithOptions = new List +\{ + // Define a Facet: + new Facet + \{ + // Specify the index-field for which to get count of documents per unique ITEM + FieldName = "Brand", + // Set some facets options + Options = new FacetOptions + \{ + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithOptions) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the facets options + .WithOptions(new FacetOptions + { + // Return the top 3 brands with most items count: + PageSize = 3, + TermSortMode = FacetTermSortMode.CountDesc + })) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(Brand, $p0)") + // Add the facet options to the "p0" parameter + .AddParameter("p0", new { PageSize = 3, TermSortMode = FacetTermSortMode.CountDesc }) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +var brandFacets = results["Brand"]; +var numberOfBrands = brandFacets.Values.Count; // 3 brands + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +Assert.Equal("fuji", facetValue.Range); +// Number of documents for 'Fuji' is available in the 'Count' property +Assert.Equal(4, facetValue.Count); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +List facetsWithAggregations = new List +\{ + // Define a Facet: + // =============== + new Facet + \{ + FieldName = "Brand", + Aggregations = + \{ + \{ + // Set the aggregation operation: + FacetAggregation.Sum, + // Create a HasSet specifying the index-fields for which to perform the aggregation + new HashSet + \{ + // Get total number of UnitsInStock per Brand + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price per Brand + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels per Brand + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength per Brand + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \}, + + // Define a RangeFacet: + // ==================== + new RangeFacet + \{ + Ranges = + \{ + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800 + \}, + Aggregations = + \{ + \{ + FacetAggregation.Sum, new HashSet + \{ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField \{Name = "UnitsInStock"\} + \} + \}, + \{ + FacetAggregation.Average, new HashSet + \{ + // Get average Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Min, new HashSet + \{ + // Get min Price of each group of documents per range specified + new FacetAggregationField \{Name = "Price"\} + \} + \}, + \{ + FacetAggregation.Max, new HashSet + \{ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField \{Name = "MegaPixels"\}, + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField \{Name = "MaxFocalLength"\} + \} + \} + \} + \} +\}; +`} + + +#### Query the index for facets results: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .AggregateBy(facetsWithAggregations) + .Execute(); +`} + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + .AggregateBy(builder => builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + .ByField(x => x.Brand) + // Specify the aggregations per the Brand facet: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .AndAggregateBy(builder => builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .ByRanges( + x => x.Price < 200, + x => x.Price >= 200 && x.Price < 400, + x => x.Price >= 400 && x.Price < 600, + x => x.Price >= 600 && x.Price < 800, + x => x.Price >= 800) + // Specify the aggregations per the Price range: + .SumOn(x => x.UnitsInStock) + .AverageOn(x => x.Price) + .MinOn(x => x.Price) + .MaxOn(x => x.MegaPixels) + .MaxOn(x => x.MaxFocalLength)) + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))") + // Add the parameters' values + .AddParameter("p0", 200.0) + .AddParameter("p1", 200.0) + .AddParameter("p2", 400.0) + .AddParameter("p3", 400.0) + .AddParameter("p4", 600.0) + .AddParameter("p5", 600.0) + .AddParameter("p6", 800.0) + .AddParameter("p7", 800.0) + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +var brandFacets = results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +var facetValue = brandFacets.Values[0]; +// The brand name is available in the 'Range' property: +Assert.Equal("canon", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(30, facetValue.Sum); + +// Get results for the 'Price' RangeFacets: +// ======================================= +var priceRangeFacets = results["Price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.Values[0]; +// The range string is available in the 'Range' property: +Assert.Equal("Price < 200.0", facetValue.Range); +// The index-field on which aggregation was done is in the 'Name' property: +Assert.Equal("UnitsInStock", facetValue.Name); +// The requested aggregation result: +Assert.Equal(17, facetValue.Sum); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +FacetSetup facetSetup = new FacetSetup +\{ + // Provide the ID of the document in which the facet setup will be stored. + // This is optional - + // if not provided then the session will assign an ID for the stored document. + Id = "customDocumentID", + + // Define Facets and RangeFacets to query by: + Facets = new List \{ + new Facet() + \{ + FieldName = "Brand" + \}\}, + + RangeFacets = new List + \{ + new RangeFacet + \{ + Ranges = + \{ + x => x.MegaPixels < 20, + x => x.MegaPixels >= 20 && x.MegaPixels < 30, + x => x.MegaPixels >= 30 && x.MegaPixels < 50, + x => x.MegaPixels >= 50 + \} + \} + \} +\}; + +// Store the facet setup document and save changes: +// ================================================ +session.Store(facetSetup); +session.SaveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`Dictionary results = session + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = await asyncSession + // Query the index + .Query() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .ExecuteAsync(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + .DocumentQuery() + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + .AggregateUsing("customDocumentID") + .Execute(); +`} + + + + +{`Dictionary results = session.Advanced + // Query the index + // Provide the RQL string to the RawQuery method + .RawQuery(@"from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))") + // Execute the query + .ExecuteAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`IAggregationQuery AggregateBy(FacetBase facet); +IAggregationQuery AggregateBy(IEnumerable facets); +IAggregationQuery AggregateBy(Action> builder); +IAggregationQuery AggregateUsing(string facetSetupDocumentKey); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **facets** | `IEnumerable` | Enumerable containing `FacetBase` implementations. | +| **builder** | `Action>` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`public class Facet +{ + public string FieldName { get; set; } + public FacetOptions Options { get; set; } +} + +public class Facet +{ + public Expression> FieldName { get; set; } + public FacetOptions Options { get; set; } +} +`} + + + + +{`public class RangeFacet +{ + public List Ranges { get; set; } +} + +public class RangeFacet +{ + public List>> Ranges { get; set; } +} +`} + + + + +{`public class FacetBase +{ + public Dictionary> Aggregations { get; set; } + public string DisplayFieldName { get; set; } +} +`} + + + + +{`public enum FacetAggregation +{ + None, + Max, + Min, + Average, + Sum +} +`} + + + + +**Fluent API builder methods**: + + + +{`IFacetOperations ByField(string fieldName); +IFacetOperations ByField(Expression> path); +IFacetOperations ByRanges(Expression> path, params Expression>[] paths); +IFacetOperations WithDisplayName(string displayName); +IFacetOperations WithOptions(FacetOptions options); +IFacetOperations SumOn(Expression> path); +IFacetOperations MinOn(Expression> path); +IFacetOperations MaxOn(Expression> path); +IFacetOperations AverageOn(Expression> path); +`} + + + +| Parameter | Type | Description | +|-----------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `Expression>` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SumOn`, `MinOn`, `MaxOn`, `AverageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`public class FacetOptions +\{ + public FacetTermSortMode TermSortMode \{ get; set; \} = FacetTermSortMode.ValueAsc; + public bool IncludeRemainingTerms \{ get; set; \} + public int Start \{ get; set; \} + public int PageSize \{ get; set; \} = int.MaxValue; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **TermSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **Start** | `int` | The position from which to send items (how many to skip) | +| **PageSize** | `int` | Number of items to return | +| **IncludeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-java.mdx new file mode 100644 index 0000000000..839fa2d70e --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-java.mdx @@ -0,0 +1,362 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +When displaying a large amount of data, paging is often used to make viewing the data manageable. +It's also useful to give some context of the entire data-set and a easy way to drill-down into +particular categories. The common approach to doing this is a "faceted search", as shown in the +image below. **Note** how the count of each category within the current search is across the top. + +![Facets](../assets/CNET_faceted_search.jpg) + +<br /> +Let's start with defining a document like this: + + + +{`public class Camera \{ + private Date dateOfListing; + private String model; + private double cost; + private int zoom; + private double megapixels; + private boolean imageStabilizer; + private String manufacturer; + + public Date getDateOfListing() \{ + return dateOfListing; + \} + + public void setDateOfListing(Date dateOfListing) \{ + this.dateOfListing = dateOfListing; + \} + + public String getModel() \{ + return model; + \} + + public void setModel(String model) \{ + this.model = model; + \} + + public double getCost() \{ + return cost; + \} + + public void setCost(double cost) \{ + this.cost = cost; + \} + + public int getZoom() \{ + return zoom; + \} + + public void setZoom(int zoom) \{ + this.zoom = zoom; + \} + + public double getMegapixels() \{ + return megapixels; + \} + + public void setMegapixels(double megapixels) \{ + this.megapixels = megapixels; + \} + + public boolean isImageStabilizer() \{ + return imageStabilizer; + \} + + public void setImageStabilizer(boolean imageStabilizer) \{ + this.imageStabilizer = imageStabilizer; + \} + + public String getManufacturer() \{ + return manufacturer; + \} + + public void setManufacturer(String manufacturer) \{ + this.manufacturer = manufacturer; + \} +\} +`} + + + +## Step 1 + +Create an index to work against. + + + +{`public class Cameras_ByManufacturerModelCostDateOfListingAndMegapixels extends AbstractIndexCreationTask \{ + public Cameras_ByManufacturerModelCostDateOfListingAndMegapixels() \{ + map = "from camera in docs.Cameras " + + "select new \{" + + " camera.manufacturer," + + " camera.model," + + " camera.cost," + + " camera.dateOfListing," + + " camera.megapixels" + + "\} "; + \} +\} +`} + + + +## Step 2 + +Setup your facet definitions: + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + +This tells RavenDB that you would like to get the following facets: + +* For the **manufacturer** field, look at the documents and return a count for each unique Term found. + +* For the **cost** field, return the count of the following ranges: + + * cost < 200.0 + * 200.0 <= cost < 400.0 + * 400.0 <= cost < 600.0 + * 600.0 <= cost < 800.0 + * cost >= 800.0 +* For the **megapixels** field, return the count of the following ranges: + * megapixels <= 3.0 + * 3.0 <= megapixels < 7.0 + * 7.0 <= megapixels < 10.0 + * megapixels >= 10.0 + +## Step 3 + +You can write the following code to get back the data below: + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateBy(facets) + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10) +`} + + + + +This data represents the sample faceted data that satisfies the above query: + + + +{`[ + \{ + "Name": "manufacturer", + "Values": [ + \{ + "Count": 1, + "Range": "canon" + \}, + \{ + "Count": 2, + "Range": "jessops" + \}, + \{ + "Count": 1, + "Range": "nikon" + \}, + \{ + "Count": 1, + "Range": "phillips" + \}, + \{ + "Count": 3, + "Range": "sony" + \} + ] + \}, + \{ + "Name": "cost", + "Values": [ + \{ + "Count": 6, + "Range": "cost <= 200" + \}, + \{ + "Count": 2, + "Range": "cost between 200 and 400" + \}, + \{ + "Count": 0, + "Range": "cost between 400 and 600" + \}, + \{ + "Count": 0, + "Range": "cost between 600 and 800" + \}, + \{ + "Count": 0, + "Range": "cost >= 800" + \} + ] + \}, + \{ + "Name": "megapixels", + "Values": [ + \{ + "Count": 0, + "Range": "megapixels <= 3" + \}, + \{ + "Count": 6, + "Range": "megapixels between 3 and 7" + \}, + \{ + "Count": 1, + "Range": "megapixels between 7 and 10" + \}, + \{ + "Count": 1, + "Range": "megapixels >= 10" + \} + ] + \} +] +`} + + + +### Storing Facets + +If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time: + + + +{`FacetSetup facetSetup = new FacetSetup(); +facetSetup.setFacets(facets); +facetSetup.setRangeFacets(rangeFacets); + +session.store(facetSetup, "facets/CameraFacets"); +`} + + + + + + +{`Map facetResults = session + .query(Camera.class, Cameras_ByManufacturerModelCostDateOfListingAndMegapixels.class) + .whereBetween("cost", 100, 300) + .aggregateUsing("facets/CameraFacets") + .execute(); +`} + + + + +{`Facet facet1 = new Facet(); +facet1.setFieldName("manufacturer"); + +RangeFacet facet2 = new RangeFacet(); +facet2.setRanges(Arrays.asList( + "cost <= 200", + "cost between 200 and 400", + "cost between 400 and 600", + "cost between 600 and 800", + "cost >= 800" +)); + +RangeFacet facet3 = new RangeFacet(); +facet3.setRanges(Arrays.asList( + "megapixels < 3", + "megapixels between 3 and 7", + "megapixels between 7 and 10", + "megapixels >= 10" +)); + +List facets = Arrays.asList(facet1); +List rangeFacets = Arrays.asList(facet2, facet3); +`} + + + + +{`from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' +where cost between 100 and 300 +select facet(id('facets/CameraFacets')) +`} + + + + +### Stale Results + +The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method. + +### Fluent API + +As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search.mdx). + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-nodejs.mdx new file mode 100644 index 0000000000..469e9e94d1 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-nodejs.mdx @@ -0,0 +1,918 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera { + constructor( + manufacturer = '', + cost = 0, + megaPixels = 0, + maxFocalLength = 0, + unitsInStock = 0 + ) { + Object.assign(this, { + manufacturer, + cost, + megaPixels, + maxFocalLength, + unitsInStock + }); + } +} +`} + + + + +{`class Cameras_ByFeatures extends AbstractJavaScriptIndexCreationTask { + constructor () { + super(); + + this.map("Cameras", camera => { + return { + brand: camera.manufacturer, + price: camera.cost, + megaPixels: camera.megaPixels, + maxFocalLength: camera.maxFocalLength, + unitsInStock: camera.unitsInStock + }; + }); + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== +const bulkInsert = store.bulkInsert(); + +const cameras = [ + new Camera("Sony", 100, 20.1, 200, 10), + new Camera("Sony", 200, 29, 250, 15), + new Camera("Nikon", 120, 22.3, 300, 2), + new Camera("Nikon", 180, 32, 300, 5), + new Camera("Nikon", 220, 40, 300, 20), + new Camera("Canon", 200, 30.4, 400, 30), + new Camera("Olympus", 250, 32.5, 600, 4), + new Camera("Olympus", 390, 40, 600, 6), + new Camera("Fuji", 410, 45, 700, 1), + new Camera("Fuji", 590, 45, 700, 5), + new Camera("Fuji", 650, 61, 800, 17), + new Camera("Fuji", 850, 102, 800, 19) +]; + +for (const camera of cameras) { + await bulkInsert.store(camera); +} + +await bulkInsert.finish(); +`} + + + + + + +## Facets - Basics + + + +**Facets definition**: +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a Facet: +// =============== +const brandFacet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique brand +brandFacet.fieldName = "brand"; +// Set a display name for this field in the results (optional) +brandFacet.displayFieldName = "Camera Brand"; + +// Define a RangeFacet: +// ==================== +const priceRangeFacet = new RangeFacet(); +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +priceRangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; +// Set a display name for this field in the results (optional) +priceRangeFacet.displayFieldName = "Camera Price"; + +const facets = [brandFacet, priceRangeFacet]; +`} + + + + + + + +**Query the index for facets results**: +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + .aggregateBy(...facets) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand")) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Set a display name for the field in the results (optional) + .withDisplayName("Camera Brand")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price"\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand) as "Camera Brand", + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800) as "Camera Price" +`} + + + + + + + + +**Query results**: +* **Query results** are Not the collection documents, they are of type `FacetResultObject` + which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'brand' using the display name specified: +// ============================================================================ +const brandFacets = results["Camera Brand"]; +const numberOfBrands = brandFacets.values.length; // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "canon"); +// Number of documents for 'Canon' is available in the 'count' property +assert.equal(facetValue.count, 1); + +// Get facets results for index-field 'price' using the display name specified: +// ============================================================================ +const priceFacets = results["Camera Price"]; +const numberOfRanges = priceFacets.values.length; // 5 different ranges + +// Get the aggregated facet value for a specific Range: +facetValue = priceFacets.values[0]; +assert.equal(facetValue.range, "price < 200"); // The range string +assert.equalfacetValue.count, 3); // Number of documents in this range +`} + + + + + + + +**Query further**: +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`const filteredResults = await session + .query(\{ indexName: "Cameras/ByFeatures" \}) + // Limit query results to the selected brands: + .whereIn("brand", ["Fuji", "Nikon"]) + .aggregateBy(...facets) + .execute(); +`} + + + + + + + +## Facets - Options + + + +**Facets definition**: +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `pageSize` - Number of items to return. + * `includeRemainingTerms` - Show summary of items that didn't make it into the requested pageSize. + * `termSortMode` - Set the sort order on the resulting items. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +facet.fieldName = "brand"; + +// Set some facet options +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +facet.options = facetOptions; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(facet) + .execute(); +`} + + + + +{`// Set facet options to use in the following query +// E.g.: Return top 3 brands with most items count +const facetOptions = new FacetOptions(); +facetOptions.pageSize = 3; +facetOptions.termSortMode = "CountDesc"; + +const results = await session + //Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Call 'withOptions', pass the facets options + .withOptions(facetOptions)) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(brand, $p0)\`) + // Add the facet options to the "p0" parameter + .addParameter("p0", { "termSortMode": "CountDesc", "pageSize": 3 }) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(brand, $p0) +{"p0": { "termSortMode": "CountDesc", "pageSize": 3 }} +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain: +// ================================= + +// For the "brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'brand': +// =========================================== +const brandFacets = results["brand"]; +const numberOfBrands = brandFacets.values.length; // 3 brands + +// Get the aggregated facet value for a specific Brand: +const facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +assert.equal(facetValue.range, "fuji"); +// Number of documents for 'Fuji' is available in the 'count' property +assert.equal(facetValue.count, 4); +`} + + + + + + + +## Facets - Aggregations + + + +**Facets definition**: +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of unitsInStock per Brand + * Get the highest megaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define a Facet: +// =============== +const facet = new Facet(); +facet.fieldName = "brand"; + +// Define the index-fields to aggregate: +const unitsInStockAggregationField = new FacetAggregationField(); +unitsInStockAggregationField.name = "unitsInStock"; + +const priceAggregationField = new FacetAggregationField(); +priceAggregationField.name = "price"; + +const megaPixelsAggregationField = new FacetAggregationField(); +megaPixelsAggregationField.name = "megaPixels"; + +const maxFocalLengthAggregationField = new FacetAggregationField(); +maxFocalLengthAggregationField.name = "maxFocalLength"; + +// Define the aggregation operations: +facet.aggregations.set("Sum", [unitsInStockAggregationField]); +facet.aggregations.set("Average", [priceAggregationField]); +facet.aggregations.set("Min", [priceAggregationField]); +facet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +// Define a RangeFacet: +// ==================== +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "price < 200", + "price >= 200 and price < 400", + "price >= 400 and price < 600", + "price >= 600 and price < 800", + "price >= 800" +]; + +// Define the aggregation operations: +rangeFacet.aggregations.set("Sum", [unitsInStockAggregationField]); +rangeFacet.aggregations.set("Average", [priceAggregationField]); +rangeFacet.aggregations.set("Min", [priceAggregationField]); +rangeFacet.aggregations.set("Max", [megaPixelsAggregationField, maxFocalLengthAggregationField]); + +const facetsWithAggregations = [facet, rangeFacet]; +`} + + + + + + + +**Query the index for facets results**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facet from above + .aggregateBy(...facetsWithAggregations) + .execute(); +`} + + + + +{`// Define the index-field (e.g. 'price') that will be used by the range-facet in the query below +const range = RangeBuilder.forPath("price"); + +const results = await session + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateBy' to aggregate the data by facets + // Use a builder as follows: + .aggregateBy(builder => builder + // Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .byField("brand") + // Specify the aggregations per the brand facet: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + // Call 'andAggregateBy' to aggregate the data by also by range-facets + // Use a builder as follows: + .andAggregateBy(builder => builder + .byRanges( + // Specify the ranges within index field 'price' in order to get count per RANGE + range.isLessThan(200), + range.isGreaterThanOrEqualTo(200).isLessThan(400), + range.isGreaterThanOrEqualTo(400).isLessThan(600), + range.isGreaterThanOrEqualTo(600).isLessThan(800), + range.isGreaterThanOrEqualTo(800)) + // Specify the aggregations per the price range: + .sumOn("unitsInStock") + .averageOn("price") + .minOn("price") + .maxOn("megaPixesls") + .maxOn("maxFocalLength")) + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength))\`) + // Add the parameters' values + .addParameter("p0", 200) + .addParameter("p1", 200) + .addParameter("p2", 400) + .addParameter("p3", 400) + .addParameter("p4", 600) + .addParameter("p5", 600) + .addParameter("p6", 800) + .addParameter("p7", 800) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(brand, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)), + facet(price < 200, + price >= 200 and price < 400, + price >= 400 and price < 600, + price >= 600 and price < 800, + price >= 800, + sum(unitsInStock), + avg(price), + min(price), + max(megaPixels), + max(maxFocalLength)) +`} + + + + + + + + +**Query results**: + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "brand" Facet: +// "canon" Count:1, Sum: 30, Name: unitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: price +// "canon" Count:1, Max: 30.4, Name: megaPixels +// "canon" Count:1, Max: 400, Name: maxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: unitsInStock +// "fuji" Count:4, Min: 410, Name: price +// "fuji" Count:4, Max: 102, Name: megaPixels +// "fuji" Count:4, Max: 800, Name: maxFocalLength +// +// etc..... + +// For the "price" Ranges: +// "Price < 200" Count:3, Sum: 17, Name: unitsInStock +// "Price < 200" Count:3, Min: 100, Average: 133.33, Name: price +// "Price < 200" Count:3, Max: 32, Name: megaPixels +// "Price < 200" Count:3, Max: 300, Name: maxFocalLength +// +// "Price < 200 and Price > 400" Count:5, Sum: 75, Name: unitsInStock +// "Price < 200 and Price > 400" Count:5, Min: 200, Average: 252, Name: price +// "Price < 200 and Price > 400" Count:5, Max: 40, Name: megaPixels +// "Price < 200 and Price > 400" Count:5, Max: 600, Name: maxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'brand' Facets: +// ========================================== +const brandFacets = results["brand"]; + +// Get the aggregated facet value for a specific brand: +let facetValue = brandFacets.values[0]; +// The brand name is available in the 'range' property: +assert.equal(facetValue.range, "canon"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 30); + +// Get results for the 'price' RangeFacets: +// ======================================= +const priceRangeFacets = results["price"]; + +// Get the aggregated facet value for a specific Brand: +facetValue = priceRangeFacets.values[0]; +// The range string is available in the 'range' property: +assert.equal(facetValue.range, "price < 200"); +// The index-field on which aggregation was done is in the 'name' property: +assert.equal(facetValue.name, "unitsInStock"); +// The requested aggregation result: +assert.equal(facetValue.sum, 17); +`} + + + + + + + +## Storing facets definition in a document + + + + + +**Define and store facets in a document**: +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +const facetSetup = new FacetSetup(); + +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +facetSetup.id = "customDocumentID"; + +// Define Facets and RangeFacets to query by: +const facet = new Facet(); +facet.fieldName = 'brand'; + +facetSetup.facets = [facet]; + +const rangeFacet = new RangeFacet(); +rangeFacet.ranges = [ + "megaPixels < 20", + "megaPixels >= 20 and megaPixels < 30", + "megaPixels >= 30 and megaPixels < 50", + "megaPixels >= 50" +]; + +facetSetup.rangeFacets = [rangeFacet]; + +// Store the facet setup document and save changes: +// ================================================ +await session.store(facetSetup); +await session.saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + + + + + + +**Query using facets from document**: + + + +{`const results = await session + // Query the index + .query({ indexName: "Cameras/ByFeatures" }) + // Call 'aggregateUsing' + // Pass the ID of the document that contains your facets setup + .aggregateUsing("customDocumentID") + .execute(); +`} + + + + +{`const results = await session.advanced + // Query the index + // Provide the RQL string to the rawQuery method + .rawQuery(\`from index "Cameras/ByFeatures" + select facet(id("customDocumentID"))\`) + // Execute the query + .executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + + + +## Syntax + + + +{`// Aggregate data by Facets: +aggregateBy(facet); +aggregateBy(...facet); +aggregateBy(action); + +// Aditional aggregation for another Facet/RangeFacet (use with fluent API) +andAggregateBy(facet); +andAggregateBy(builder); + +// Aggregate data by Facets stored in a document +aggregateUsing(facetSetupDocumentId); +`} + + + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------------------| +| **facet** | `FacetBase` | `FacetBase` implementation defining the facet and its options.
Either `Facet` or `RangeFacet`. | +| **...facet** | `FacetBase[]` | List containing `FacetBase` implementations. | +| **action** / **builder** | `(builder) => void` | Builder with a fluent API that constructs a `FacetBase` instance. | +| **facetSetupDocumentId** | `string` | ID of a document containing `FacetSetup`. | + + + + +{`class Facet { + fieldName; +} +`} + + + + +{`class RangeFacet { + ranges; +} +`} + + + + +{`class FacetBase { + displayFieldName; + options; + aggregations; // "None" | "Max" | "Min" | "Average" | "Sum" +} +`} + + + + +**builder methods**: + + + +{`byField(fieldName); +byRanges(range, ...ranges); + +withDisplayName(displayName); +withOptions(options); + +sumOn(path); +sumOn(path, displayName); + +minOn(path); +minOn(path, displayName); + +maxOn(path); +maxOn(path, displayName); + +averageOn(path); +averageOn(path, displayName); +`} + + + +| Parameter | Type | Description | +|-----------------|----------------|------------------------------------------------------------------------------------------------------------------------------| +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | The index-field to use for the facet (`byRanges`, `byField`) or for the aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + +**Options**: + + + +{`class FacetOptions \{ + termSortMode; + includeRemainingTerms; + start; + pageSize; +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`ValueAsc` (Default), `ValueDesc`, `CountAsc`, `CountDesc`) | +| **start** | `number` | The position from which to send items (how many to skip) | +| **pageSize** | `number` | Number of items to return | +| **includeRemainingTerms** | `boolean` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results | + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-php.mdx new file mode 100644 index 0000000000..568a10be8d --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-php.mdx @@ -0,0 +1,1094 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera +{ + private ?string $manufacturer = null; + private ?float $cost = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function __construct( + ?string $manufacturer = null, + ?float $cost = null, + ?float $megaPixels = null, + ?int $maxFocalLength = null, + ?int $unitsInStock = null, + ) + { + $this->manufacturer = $manufacturer; + $this->cost = $cost; + $this->megaPixels = $megaPixels; + $this->maxFocalLength = $maxFocalLength; + $this->unitsInStock = $unitsInStock; + } + + public function getManufacturer(): ?string + { + return $this->manufacturer; + } + + public function setManufacturer(?string $manufacturer): void + { + $this->manufacturer = $manufacturer; + } + + public function getCost(): ?float + { + return $this->cost; + } + + public function setCost(?float $cost): void + { + $this->cost = $cost; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} +`} + + + + +{`class Cameras_ByFeatures_IndexEntry +{ + private ?string $brand = null; + private ?float $price = null; + private ?float $megaPixels = null; + private ?int $maxFocalLength = null; + private ?int $unitsInStock = null; + + public function getBrand(): ?string + { + return $this->brand; + } + + public function setBrand(?string $brand): void + { + $this->brand = $brand; + } + + public function getPrice(): ?float + { + return $this->price; + } + + public function setPrice(?float $price): void + { + $this->price = $price; + } + + public function getMegaPixels(): ?float + { + return $this->megaPixels; + } + + public function setMegaPixels(?float $megaPixels): void + { + $this->megaPixels = $megaPixels; + } + + public function getMaxFocalLength(): ?int + { + return $this->maxFocalLength; + } + + public function setMaxFocalLength(?int $maxFocalLength): void + { + $this->maxFocalLength = $maxFocalLength; + } + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Cameras_ByFeatures extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = + "from camera in docs.Cameras " . + "select new " . + "{ " . + " brand = camera.manufacturer," . + " price = camera.cost," . + " megaPixels = camera.megaPixels," . + " maxFocalLength = camera.maxFocalLength," . + " unitsInStock = camera.unitsInStock" . + "}"; + } +} +`} + + + + +{`// Creating sample data for the examples in this article: +// ====================================================== + +$cameras = []; + +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 100, $megaPixels = 20.1, $maxFocalLength = 200, $unitsInStock = 10 ); +$cameras[] = new Camera ( $manufacturer = "Sony", $cost = 200, $megaPixels = 29, $maxFocalLength = 250, $unitsInStock = 15 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 120, $megaPixels = 22.3, $maxFocalLength = 300, $unitsInStock = 2 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 180, $megaPixels = 32, $maxFocalLength = 300, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Nikon", $cost = 220, $megaPixels = 40, $maxFocalLength = 300, $unitsInStock = 20 ); +$cameras[] = new Camera ( $manufacturer = "Canon", $cost = 200, $megaPixels = 30.4, $maxFocalLength = 400, $unitsInStock = 30 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 250, $megaPixels = 32.5, $maxFocalLength = 600, $unitsInStock = 4 ); +$cameras[] = new Camera ( $manufacturer = "Olympus", $cost = 390, $megaPixels = 40, $maxFocalLength = 600, $unitsInStock = 6 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 410, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 1 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 590, $megaPixels = 45, $maxFocalLength = 700, $unitsInStock = 5 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 650, $megaPixels = 61, $maxFocalLength = 800, $unitsInStock = 17 ); +$cameras[] = new Camera ( $manufacturer = "Fuji", $cost = 850, $megaPixels = 102, $maxFocalLength = 800, $unitsInStock = 19 ); + +$session = $store->openSession(); +try { + foreach ($cameras as $camera) + { + $session->store($camera); + } + + $session->saveChanges(); +} finally { + $session->close(); +} +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets to aggregate the data by. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`// Define a list of facets to query by: +// ==================================== +$facets = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +// Specify the index-field for which to get count of documents per unique ITEM +// e.g. get the number of Camera documents for each unique Brand +$facet->setFieldName("Brand"); +// Set a display name for this field in the results (optional) +$facet->setDisplayFieldName("Camera Brand"); + +$facets[] = $facet; + +// Define a RangeFacet: for Cameras_ByFeatures_IndexEntry +// ==================== +$rangeFacet = new RangeFacet(); + +// Specify ranges within an index-field in order to get count per RANGE +// e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +$rangeFacet->setRanges([ + "price < 200", + "price >= 200 and price <= 400", + "price >= 400 and price <= 600", + "price >= 600 and price <= 800", + "price >= 800" +]); + +// Set a display name for this field in the results (optional) +$rangeFacet->setDisplayFieldName("Camera Price"); + +$facets[] = $rangeFacet; +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facets) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + return $builder + // Specify the index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Brand"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Set a display name for the field in the results (optional) + ->withDisplayName("Camera Price"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand) as 'Camera Brand', + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as 'Camera Price'" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`// The resulting aggregations per display name will contain: +// ========================================================= + +// For the "Camera Brand" Facet: +// "canon" - Count: 1 +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 +// "sony" - Count: 2 + +// For the "Camera Price" Ranges: +// "Price < 200" - Count: 3 +// "Price >= 200.0 and Price < 400.0" - Count: 5 +// "Price >= 400.0 and Price < 600.0" - Count: 2 +// "Price >= 600.0 and Price < 800.0" - Count: 1 +// "Price >= 800.0" - Count: 1 +`} + + + + +{`// Get facets results for index-field 'Brand' using the display name specified: +// ============================================================================ +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Camera Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 5 unique brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index + +$this->assertEquals("canon", $facetValue->getRange()); +// Number of documents for 'Canon' is available in the 'Count' property +$this->assertEquals(1, $facetValue->getCount()); + +// Get facets results for index-field 'Price' using the display name specified: +// ============================================================================ +/** @var FacetResult $priceFacets */ +$priceFacets = $results["Camera Price"]; +$numberOfRanges = count($priceFacets->getValues()); // 5 different ranges + +// Get the aggregated facet value for a specific Range: +/** @var FacetValue $facetValue */ +$facetValue = $priceFacets->getValues()[0]; +$this->assertEquals("Price < 200", $facetValue->getRange()); // The range string +$this->assertEquals(3, $facetValue->getCount()); // Number of documents in this range +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`$filteredResults = $session + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Limit query results to the selected brands: + ->whereIn("Brand", ["Fuji", "Nikon"]) + ->aggregateBy($facets) + ->execute(); +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + * `Start` - The position from which to send items (how many to skip). + * `PageSize` - Number of items to return. + * `IncludeRemainingTerms` - Show summary of items that didn't make it into the requested PageSize. + * `TermSortMode` - Set the sort order on the resulting items. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithOptions = []; + + // Define a Facet: +$facet = new Facet(); + +// Specify the index-field for which to get count of documents per unique ITEM +$facet->setFieldName("Brand"); + +// Set some facets options +$options = new FacetOptions(); +// Return the top 3 brands with most items count: +$options->setPageSize(3); +$options->setTermSortMode(FacetTermSortMode::countDesc()); + +$facet->setOptions($options); + +$facetsWithOptions[] = $facet; +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'aggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithOptions) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + $options = new FacetOptions(); + // Return the top 3 brands with most items count: + $options->setPageSize(3); + $options->setTermSortMode(FacetTermSortMode::countDesc()); + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the facets options + ->withOptions($options); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, "from index 'Cameras/ByFeatures'select facet(Brand, \\$p0)") + // Add the facet options to the "p0" parameter + ->addParameter("p0", [ "PageSize" => 3, "TermSortMode" => FacetTermSortMode::countDesc() ]) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`// The resulting items will contain: +// ================================= + +// For the "Brand" Facet: +// "fuji" - Count: 4 +// "nikon" - Count: 3 +// "olympus" - Count: 2 + +// As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`// Get facets results for index-field 'Brand': +// =========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; +$numberOfBrands = count($brandFacets->getValues()); // 3 brands + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property +// Note: value is lower-case since the default RavenDB analyzer was used by the index +$this::assertEquals("fuji", $facetValue->getRange()); +// Number of documents for 'Fuji' is available in the 'Count' property +$this->assertEquals(4, $facetValue->getCount()); +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * sum + * average + * min + * max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`// Define the list of facets to query by: +// ====================================== +$facetsWithAggregations = []; + +// Define a Facet: +// =============== +$facet = new Facet(); +$facet->setFieldName("Brand"); + +$aggregations = new AggregationArray(); + +$aggregations->set( + // Set the aggregation operation: + FacetAggregation::sum(), + // Get total number of UnitsInStock for each group of documents per range specified + [ + // Get total number of UnitsInStock per Brand + new FacetAggregationField($name = "UnitsInStock") + ] +); + +$aggregations->set(FacetAggregation::average(), [ + // Get average Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::min(), [ + // Get min Price per Brand + new FacetAggregationField($name = "Price") +]); + +$aggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels per Brand + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength per Brand + new FacetAggregationField($name = "MaxFocalLength") +]); + +$facet->setAggregations($aggregations); + +// Define a RangeFacet: +// ==================== +$rangeFacet = new RangeFacet(); +$rangeFacet->setRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" +]); + +$rangeAggregations = new AggregationArray(); + +$rangeAggregations->set(FacetAggregation::sum(), [ + // Get total number of UnitsInStock for each group of documents per range specified + new FacetAggregationField($name = "UnitsInStock") +]); +$rangeAggregations->set(FacetAggregation::average(), [ + // Get average Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); +$rangeAggregations->set(FacetAggregation::min(), [ + // Get min Price of each group of documents per range specified + new FacetAggregationField($name = "Price") +]); + +$rangeAggregations->set(FacetAggregation::max(), [ + // Get max MegaPixels for each group of documents per range specified + new FacetAggregationField($name = "MegaPixels"), + // Get max MaxFocalLength for each group of documents per range specified + new FacetAggregationField($name = "MaxFocalLength") + +]); + +$rangeFacet->setAggregations($rangeAggregations); +`} + + +#### Query the index for facets results: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Pass the defined facets from above + ->aggregateBy($facetsWithAggregations) + ->execute(); +`} + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateBy' to aggregate the data by facets + // Use a builder as follows: + ->aggregateBy(function($builder) { + + return $builder + // Specify an index-field (e.g. 'Brand') for which to get count per unique ITEM + ->byField("Brand") + // Specify the aggregations per the Brand facet: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->andAggregateBy(function($builder) { + return $builder + // Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + ->byRanges([ + "Price < 200", + "Price >= 200 && Price < 400", + "Price >= 400 && Price < 600", + "Price >= 600 && Price < 800", + "Price >= 800" + ]) + // Specify the aggregations per the Price range: + ->sumOn("UnitsInStock") + ->averageOn("Price") + ->minOn("Price") + ->maxOn("MegaPixels") + ->maxOn("MaxFocalLength"); + }) + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery(Camera::class, + "from index 'Cameras/ByFeatures' + select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < \\$p0, + Price >= \\$p1 and Price < \\$p2, + Price >= \\$p3 and Price < \\$p4, + Price >= \\$p5 and Price < \\$p6, + Price >= \\$p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength))" + ) + // Add the parameters' values + ->addParameter("p0", 200.0) + ->addParameter("p1", 200.0) + ->addParameter("p2", 400.0) + ->addParameter("p3", 400.0) + ->addParameter("p4", 600.0) + ->addParameter("p5", 600.0) + ->addParameter("p6", 800.0) + ->addParameter("p7", 800.0) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`// The resulting items will contain (Showing partial results): +// =========================================================== + +// For the "Brand" Facet: +// "canon" Count:1, Sum: 30, Name: UnitsInStock +// "canon" Count:1, Min: 200, Average: 200, Name: Price +// "canon" Count:1, Max: 30.4, Name: MegaPixels +// "canon" Count:1, Max: 400, Name: MaxFocalLength +// +// "fuji" Count:4, Sum: 42, Name: UnitsInStock +// "fuji" Count:4, Min: 410, Name: Price +// "fuji" Count:4, Max: 102, Name: MegaPixels +// "fuji" Count:4, Max: 800, Name: MaxFocalLength +// +// etc..... + +// For the "Price" Ranges: +// "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +// "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +// "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +// "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength +// +// "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +// "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +// "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +// "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength +// +// etc..... +`} + + + + +{`// Get results for the 'Brand' Facets: +// ========================================== +/** @var FacetResult $brandFacets */ +$brandFacets = $results["Brand"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $brandFacets->getValues()[0]; +// The brand name is available in the 'Range' property: +$this->assertEquals("canon", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(30, $facetValue->getSum()); + +// Get results for the 'Price' RangeFacets: +// ======================================= +/** @var FacetResult $priceRangeFacets */ +$priceRangeFacets = $results["Price"]; + +// Get the aggregated facet value for a specific Brand: +/** @var FacetValue $facetValue */ +$facetValue = $priceRangeFacets->getValues()[0]; +// The range string is available in the 'Range' property: +$this->assertEquals("Price < 200.0", $facetValue->getRange()); +// The index-field on which aggregation was done is in the 'Name' property: +$this->assertEquals("UnitsInStock", $facetValue->getName()); +// The requested aggregation result: +$this->assertEquals(17, $facetValue->getSum()); +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`// Create a FacetSetup object: +// =========================== +$facetSetup = new FacetSetup(); +// Provide the ID of the document in which the facet setup will be stored. +// This is optional - +// if not provided then the session will assign an ID for the stored document. +$facetSetup->setId("customDocumentID"); + +// Define Facets and RangeFacets to query by: +$facetSetup->setFacets([ + new Facet("Brand") +]); + + +$facetSetup->setRangeFacets([ + new RangeFacet( + $parent = null, + $ranges = [ + "MegaPixels < 20", + "MegaPixels >= 20 && MegaPixels < 30", + "MegaPixels >= 30 && MegaPixels < 50", + "MegaPixels >= 50" + ] + ) +]); + +// Store the facet setup document and save changes: +// ================================================ +$session->store($facetSetup); +$session->saveChanges(); + +// The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`$results = $session + // Query the index + ->query(Cameras_ByFeatures_IndexEntry::class, Cameras_ByFeatures::class) + // Call 'AggregateUsing' + // Pass the ID of the document that contains your facets setup + ->aggregateUsing("customDocumentID") + ->execute(); +`} + + + + +{`$results = $session->advanced() + // Query the index + // Provide the RQL string to the RawQuery method + ->rawQuery( + $className = Camera::class, + $query = "from index 'Cameras/ByFeatures' + select facet(id('customDocumentID'))" + ) + // Execute the query + ->executeAggregation(); +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`public function aggregateBy(Callable|FacetBase|FacetBaseArray|array ...$builderOrFacets): AggregationDocumentQueryInterface; + +// You can call it +// ->aggregateBy(FacetBase $facet); +// ->aggregateBy(FacetBase $facet1, FacetBase $facet2, ...); +// ->aggregateBy(FacetBaseArray|array $facets); +// ->aggregateBy(function(FacetBuilderInterface $builder) \{ ...\}); + +public function aggregateUsing(?string $facetSetupDocumentId): AggregationDocumentQueryInterface; +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builderOrFacets** | `Callable` **or** `FacetBase` **or** `FacetBaseArray` **or** `array` | Builder with a fluent API that constructs a `FacetBase` implementation instance **or** `FacetBase` implementation instance | +| **facets** | `FacetBaseArray` **or** `array` | A list of `FacetBase` implementations instances. | +| **facetSetupDocumentId** | `string ` | ID of a document containing `FacetSetup` | + + + + +{`class Facet +{ + private ?string $fieldName = null; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class RangeFacet +{ + private StringArray $ranges; + private ?FacetOptions $options = null; + + // ... getters and setters +} +`} + + + + +{`class FacetBase +{ + private ?AggregationArray $aggregations = null; + private ?string $displayFieldName = null; + + // ... getters and setters +} +`} + + + + +{`interface FacetAggregation +{ + public function isNone(): bool; + public function isMax(): bool; + public function isMin(): bool; + public function isAverage(): bool; + public function isSum(): bool; + + public static function none(): FacetAggregation; + public static function max(): FacetAggregation; + public static function min(): FacetAggregation; + public static function average(): FacetAggregation; + public static function sum(): FacetAggregation; +} +`} + + + + +**Fluent API builder methods**: + + + +{`public function byField(string $fieldName): FacetOperationsInterface; +public function byRanges(?RangeBuilder $range, ?RangeBuilder ...$ranges): FacetOperationsInterface; + +public function withDisplayName(string $displayName): FacetOperationsInterface; +public function withOptions(FacetOptions $options): FacetOperationsInterface; + +public function sumOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function minOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function maxOn(string $path, ?string $displayName = null): FacetOperationsInterface; +public function averageOn(string $path, ?string $displayName = null): FacetOperationsInterface; +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range** | `RangeBuilder` | A range of indexes | +| **ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **fieldName** | `string` | The index-field to use for the facet | +| **path** | `string` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **displayName** | `string` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions +\{ + private FacetTermSortMode $termSortMode; // default value FacetTermSortMode::valueAsc() + private bool $includeRemainingTerms = false; + private int $start = 0; + private int $pageSize = 0; + + // ... getters and setters +\} +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **termSortMode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **pageSize** | `int` | Number of items to return | +| **includeRemainingTerms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-python.mdx new file mode 100644 index 0000000000..ffa929e6a9 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_faceted-search-python.mdx @@ -0,0 +1,945 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* A **Faceted Search** provides an efficient way to explore and navigate through large datasets or search results. + +* Multiple filters (facets) are applied to narrow down the search results according to different attributes or categories. + +![Facets](../assets/CNET_faceted_search.jpg) +* In this page + * [Define an index](../../indexes/querying/faceted-search.mdx#define-an-index) + * [Facets - Basics](../../indexes/querying/faceted-search.mdx#facets---basics) + * [Facets - Options](../../indexes/querying/faceted-search.mdx#facets---options) + * [Facets - Aggregations](../../indexes/querying/faceted-search.mdx#facets---aggregations) + * [Storing facets definition in a document](../../indexes/querying/faceted-search.mdx#storing-facets-definition-in-a-document) + * [Syntax](../../indexes/querying/faceted-search.mdx#syntax) + + +## Define an index + +* To make a faceted search, **a static-index must be defined** for the fields you want to query and apply facets on. + +* The examples in this article will be based on the following Class, Index, and Sample Data: + + + + +{`class Camera: + def __init__( + self, + manufacturer: str = None, + cost: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.manufacturer = manufacturer + self.cost = cost + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock +`} + + + + +{`class Cameras_ByFeatures(AbstractIndexCreationTask): + class IndexEntry: + def __init__( + self, + brand: str = None, + price: float = None, + mega_pixels: float = None, + max_focal_length: int = None, + units_in_stock: int = None, + ): + self.brand = brand + self.price = price + self.mega_pixels = mega_pixels + self.max_focal_length = max_focal_length + self.units_in_stock = units_in_stock + + def __init__(self): + super().__init__() + self.map = ( + "from camera in docs.Cameras " + "select new " + "{ " + " brand = camera.manufacturer," + " price = camera.cost," + " mega_pixels = camera.mega_pixels," + " max_focal_length = camera.max_focal_length," + " units_in_stock = camera.units_in_stock" + "}" + ) +`} + + + + +{`# Creating sample data for the examples in this article: +# ====================================================== + +cameras = [ + Camera(manufacturer="Sony", cost=100, mega_pixels=20.1, max_focal_length=200, units_in_stock=10), + Camera(manufacturer="Sony", cost=200, mega_pixels=29, max_focal_length=250, units_in_stock=15), + Camera(manufacturer="Nikon", cost=120, mega_pixels=22.3, max_focal_length=300, units_in_stock=2), + Camera(manufacturer="Nikon", cost=180, mega_pixels=32, max_focal_length=300, units_in_stock=5), + Camera(manufacturer="Nikon", cost=220, mega_pixels=40, max_focal_length=300, units_in_stock=20), + Camera(manufacturer="Canon", cost=200, mega_pixels=30.4, max_focal_length=400, units_in_stock=30), + Camera(manufacturer="Olympus", cost=250, mega_pixels=32.5, max_focal_length=600, units_in_stock=4), + Camera(manufacturer="Olympus", cost=390, mega_pixels=40, max_focal_length=600, units_in_stock=6), + Camera(manufacturer="Fuji", cost=410, mega_pixels=45, max_focal_length=700, units_in_stock=1), + Camera(manufacturer="Fuji", cost=590, mega_pixels=45, max_focal_length=700, units_in_stock=5), + Camera(manufacturer="Fuji", cost=650, mega_pixels=61, max_focal_length=800, units_in_stock=17), + Camera(manufacturer="Fuji", cost=850, mega_pixels=102, max_focal_length=800, units_in_stock=19), +] + +with store.open_session() as session: + for camera in cameras: + session.store(camera) + session.save_changes() +`} + + + + + + +## Facets - Basics + +#### Facets definition: + +* Define a list of facets by which to aggregate the data. + +* There are two **Facet types**: + * `Facet` - returns a count for each unique term found in the specified index-field. + * `RangeFacet` - returns a count per range within the specified index-field. + + + +{`# Define a Facet: +# =============== +facet = Facet( + # Specify the index-field for which to get count of documents per unique ITEM + # e.g. get the number of Camera documents for each unique brand + field_name="brand", +) + +# Set a display name for this field in the results (optional) +facet.display_field_name = "Camera Brand" + +# Define a RangeFacet: +# ==================== +range_facet = RangeFacet() +# Specify ranges within an index-field in order to get count per RANGE +# e.g. get the number of Camera documents that cost below 200, between 200 & 400, etc... +range_facet.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] + +# Set a display name for this field in the results (optional) +range_facet.display_field_name = "Camera Price" + +# Define a list of facets to query by: +# ==================================== +facets = [facet, range_facet] +`} + + +#### Query the index for facets results: + +* Query the index to get the aggregated facets information. + +* Either: + + * Pass the facets definition from above directly to the query + + * Or - construct a facet using a builder with the Fluent API option, as shown below. + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets).execute() +) +`} + + + + +{`# Query the index +results = ( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify the index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Set a display name for the field in the results (optional) + .with_display_name("Camera Brand") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'Price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Set a display name for the field in the results (optional) + .with_display_name("Camera Price") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select + facet(brand) as 'Camera Brand', + facet(price < 200.0, + price >= 200.0 and price < 400.0, + price >= 400.0 and price < 600.0, + price >= 600.0 and price < 800.0, + price >= 800.0) as 'Camera Price'""", + object_type=Camera, + ) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand) as "Camera Brand", + facet(Price < 200.0, + Price >= 200.0 and Price < 400.0, + Price >= 400.0 and Price < 600.0, + Price >= 600.0 and Price < 800.0, + Price >= 800.0) as "Camera Price" +`} + + + +#### Query results: + +* **Query results** are Not the collection documents, they are of type: + `Dict[str, FacetResult]` which is the facets results per index-field specified. + +* Using the sample data from this article, the resulting aggregations will be: + + + +{`# The resulting aggregations per display name will contain: +# ========================================================= + +# For the "Camera Brand" Facet: +# "canon" - Count: 1 +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# "sony" - Count: 2 + +# For the "Camera Price" Ranges: +# "price < 200" - Count: 3 +# "200 <= price < 400" - Count: 5 +# "400 <= price < 600" - Count: 2 +# "600 <= price < 800" - Count: 1 +# "price >= 800" - Count: 1 +`} + + + + +{`# Get facets results for index-field 'brand' using the display name specified: +# ============================================================================ +brand_facets = results["Camera Brand"] +number_of_brands = len(brand_facets.values) # 5 unique brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("canon", facet_value.range_) +# Number of documents for 'Canon' is available in the 'Count' property +self.assertEqual(1, facet_value.count_) + +# Get facets results for index-field 'Price' using the display name specified: +# ============================================================================ +price_facets = results["Camera Price"] +number_of_ranges = len(price_facets.values) # 5 different ranges + +# Get the aggregated facet value for a specific Range: +facet_value = price_facets.values[0] +self.assertEqual("price < 200", facet_value.range_) # The range string +self.assertEqual(3, facet_value.count_) +`} + + + + + +**Query further**: + +* Typically, after presenting users with the initial facets results which show the available options, + users can select specific categories to explore further. + +* For example, if the user selects Fuji and Nikon, + then your next query can include a filter to focus only on those selected brands. + + + +{`filtered_results = list( + session.query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + .where_in("brand", ["Fuji", "Nikon"]) + .aggregate_by_facets(facets) + .execute() +) +`} + + + + + + + +## Facets - Options + +#### Facets definition: + +* **Options** are available only for the `Facet` type. + +* Available options: + + * `start` - The position from which to send items (how many to skip). + * `page_size` - Number of items to return. + * `include_remaining_terms` - Show summary of items that didn't make it into the requested PageSize. + * `term_sort_mode` - Set the sort order on the resulting items. + + + +{`# Define the list of facets to query by: +# ====================================== +facets_with_options = [ + # Define a Facet: + Facet( + # Specify the index-field for which to get count of documents per unique ITEM + field_name="brand", + ) +] +# Set some facets options +# Assign facet options after creating the object +facets_with_options[0].options = FacetOptions() +# Return the top 3 brands with most items count: +facets_with_options[0].options.page_size = 3 +facets_with_options[0].options.term_sort_mode = FacetTermSortMode.COUNT_DESC +facets_with_options[0].options.start = 0 +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_options).execute() +) +`} + + + + +{`# Return the top 3 brands with most items count: +facet_options = FacetOptions() +facet_options.start = 0 +facet_options.page_size = 3 +facet_options.term_sort_mode = FacetTermSortMode.COUNT_DESC + +results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the facets options + .with_options(facet_options) + ).execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """from index 'Cameras/ByFeatures' + select facet(brand, $p0)""", + object_type=Camera, + ) + # Add the facet options to the "p0" parameter + .add_parameter("p0", {"PageSize": 3, "TermSortMode": FacetTermSortMode.COUNT_DESC}) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(Brand, $p0) +{"p0": { "TermSortMode": "CountDesc", "PageSize": 3 }} +`} + + + +#### Query results: + + + +{`# The resulting items will contain: +# ================================= +# For the "brand" Facet: +# "fuji" - Count: 4 +# "nikon" - Count: 3 +# "olympus" - Count: 2 +# As requested, only 3 unique items are returned, ordered by documents count descending: +`} + + + + +{`# Get facets results for index-field 'brand': +# =========================================== +brand_facets = results["brand"] +number_of_brands = len(brand_facets.values) # 3 brands + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property +# Note: value is lower-case since the default RavenDB analyzer was used by the index +self.assertEqual("fuji", facet_value.range_) +# Number of documents for 'Fuji' is available in the 'Count' property +self.assertEqual(4, facet_value.count_) +`} + + + + + +## Facets - Aggregations + +#### Facets definition: + +* Aggregation of data is available for an index-field per unique Facet or Range item. + For example: + * Get the total number of UnitsInStock per Brand + * Get the highest MegaPixels value for documents that cost between 200 & 400 + +* The following aggregation operations are available: + * Sum + * Average + * Min + * Max + +* Multiple operations can be added on each facet, for multiple fields. + + + +{`# Define the list of facets to query by: +# ===================================== + +# Define a facet: +# =============== +facet_with_aggregations = Facet() +facet_with_aggregations.field_name = "brand" +facet_with_aggregations.aggregations = \{ + # Set the aggregation operation: + FacetAggregation.SUM: + # Create a set specifying the index-fields for which to perform the aggregation + \{ + # Get total number of units_in_stock per brand + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price per brand + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels per brand + FacetAggregationField("mega_pixels"), + # Get max max_focal_length per brand + FacetAggregationField("max_focal_length"), + \}, +\} + +# Define a RangeFacet: +# =================== +range_facet_with_aggregations = RangeFacet() +range_facet_with_aggregations.ranges = [ + "price < 200", + "price between 200 and 400", + "price between 400 and 600", + "price between 600 and 800", + "price >= 800", +] +range_facet_with_aggregations.aggregations = \{ + FacetAggregation.SUM: \{ + # Get total number of units_in_stock for each group of documents per range specified + FacetAggregationField("units_in_stock") + \}, + FacetAggregation.AVERAGE: \{ + # Get average price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MIN: \{ + # Get min price of each group of documents per range specified + FacetAggregationField("price") + \}, + FacetAggregation.MAX: \{ + # Get max mega_pixels for each group of documents per range specified + FacetAggregationField("mega_pixels"), + # Get max max_focal_length for each group of documents per range specified + FacetAggregationField("max_focal_length"), + \}, +\} + +facets_with_aggregations = [facet_with_aggregations, range_facet_with_aggregations] +`} + + +#### Query the index for facets results: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by_facets' to aggregate the data by facets + # Pass the defined facets from above + .aggregate_by_facets(facets_with_aggregations).execute() +) +`} + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_by' to aggregate the data by facets + # Use a builder as follows: + .aggregate_by( + lambda builder: builder + # Specify an index-field (e.g. 'brand') for which to get count per unique ITEM + .by_field("brand") + # Specify the aggregations per the brand facet: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .and_aggregate_by( + lambda builder: builder + # Specify ranges within an index field (e.g. 'price') in order to get count per RANGE + .by_ranges( + RangeBuilder("price").is_less_than(200), + RangeBuilder("price").is_greater_than_or_equal_to(200).is_less_than(400), + RangeBuilder("price").is_greater_than_or_equal_to(400).is_less_than(600), + RangeBuilder("price").is_greater_than_or_equal_to(600).is_less_than(800), + RangeBuilder("price").is_greater_than_or_equal_to(800), + ) + # Specify the aggregations per the price range: + .sum_on("units_in_stock") + .average_on("price") + .min_on("price") + .max_on("mega_pixels") + .max_on("max_focal_length") + ) + .execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query( + """ + from index 'Cameras/ByFeatures' + select + facet(brand, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)), + facet(price < $p0, + price >= $p1 and price < $p2, + price >= $p3 and price < $p4, + price >= $p5 and price < $p6, + price >= $p7, + sum(units_in_stock), + avg(price), + min(price), + max(mega_pixels), + max(max_focal_length)) + """ + ) + .add_parameter("p0", 200.0) + .add_parameter("p1", 200.0) + .add_parameter("p2", 400.0) + .add_parameter("p3", 400.0) + .add_parameter("p4", 600.0) + .add_parameter("p5", 600.0) + .add_parameter("p6", 800.0) + .add_parameter("p7", 800.0) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select + facet(Brand, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)), + facet(Price < $p0, + Price >= $p1 and Price < $p2, + Price >= $p3 and Price < $p4, + Price >= $p5 and Price < $p6, + Price >= $p7, + sum(UnitsInStock), + avg(Price), + min(Price), + max(MegaPixels), + max(MaxFocalLength)) +{"p0":200.0,"p1":200.0,"p2":400.0,"p3":400.0,"p4":600.0,"p5":600.0,"p6":800.0,"p7":800.0} +`} + + + +#### Query results: + + + +{`# The resulting items will contain (Showing partial results): +# =========================================================== + +# For the "brand" Facet: +# "canon" Count:1, Sum: 30, Name: UnitsInStock +# "canon" Count:1, Min: 200, Average: 200, Name: Price +# "canon" Count:1, Max: 30.4, Name: MegaPixels +# "canon" Count:1, Max: 400, Name: MaxFocalLength + +# "fuji" Count:4, Sum: 42, Name: UnitsInStock +# "fuji" Count:4, Min: 410, Name: Price +# "fuji" Count:4, Max: 102, Name: MegaPixels +# "fuji" Count:4, Max: 800, Name: MaxFocalLength + +# etc..... +# +# For the "Price" Ranges: +# "Price < 200.0" Count:3, Sum: 17, Name: UnitsInStock +# "Price < 200.0" Count:3, Min: 100, Average: 133.33, Name: Price +# "Price < 200.0" Count:3, Max: 32, Name: MegaPixels +# "Price < 200.0" Count:3, Max: 300, Name: MaxFocalLength + +# "Price < 200.0 and Price > 400.0" Count:5, Sum: 75, Name: UnitsInStock +# "Price < 200.0 and Price > 400.0" Count:5, Min: 200, Average: 252, Name: Price +# "Price < 200.0 and Price > 400.0" Count:5, Max: 40, Name: MegaPixels +# "Price < 200.0 and Price > 400.0" Count:5, Max: 600, Name: MaxFocalLength + +# etc..... +`} + + + + +{`# Get results for the 'brand' facets: +# ======================================== +brand_facets = results["brand"] + +# Get the aggregated facet value for a specific brand: +facet_value = brand_facets.values[0] +# The brand name is available in the 'Range' property: +self.assertEqual("canon", facet_value.range_) +# The index-field on which aggregation was done is in the 'name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result +self.assertEqual(30, facet_value.sum_) + +# Get results for the 'price' RangeFacets: +# ======================================== +price_range_facets = results["price"] + +# Get the aggregated facet value for a specific brand: +facet_value = price_range_facets.values[0] +# The range string is available in the 'Range' property: +self.assertEqual("price < 200", facet_value.range_) +# The index-field on which aggregation was done is in the 'Name' property: +self.assertEqual("units_in_stock", facet_value.name) +# The requested aggregation result: +self.assertEqual(17, facet_value.sum_) +`} + + + + + +## Storing facets definition in a document + +#### Define and store facets in a document: + +* The facets definitions can be stored in a document. + +* That document can then be used by a faceted search query. + + + +{`facet_setup = FacetSetup() +# Provide the ID of the document in which the facet setup will be stored. +# This is optional - +# if not provided then the session will assign an ID for the stored document. +facet_setup.Id = "customDocumentID" + +# Define Facets and RangeFacets to query by: +facet = Facet("brand") +range_facet = RangeFacet() +range_facet.ranges = [ + "mega_pixels < 20", + "mega_pixels between 20 and 30", + "mega_pixels between 30 and 50", + "mega_pixels >= 50", +] + +facet_setup.facets = [facet] +facet_setup.range_facets = [range_facet] + +# Store the facet setup document and save changes: +# =============================================== +session.store(facet_setup) +session.save_changes() + +# The document will be stored under the 'FacetSetups' collection +`} + + +#### Query using facets from document: + + + + +{`results = ( + session + # Query the index + .query_index_type(Cameras_ByFeatures, Cameras_ByFeatures.IndexEntry) + # Call 'aggregate_using' + # Pass the ID of the document that contains your facets setup + .aggregate_using("customDocumentID").execute() +) +`} + + + + +{`results = ( + session.advanced + # Query the index + # Provide the RQL string to the raw_query method + .raw_query("from index 'Cameras/ByFeatures' select facet(id('customDocumentID'))", Camera) + # Execute the query + .execute_aggregation() +) +`} + + + + +{`from index "Cameras/ByFeatures" +select facet(id("customDocumentID")) +`} + + + + + + +## Syntax + + + +{`def aggregate_by( + self, builder_or_facet: Union[Callable[[FacetBuilder], None], FacetBase] +) -> AggregationDocumentQuery[_T]: ... + +def aggregate_by_facets(self, facets: List[FacetBase]) -> AggregationDocumentQuery[_T]: ... + +def aggregate_using(self, facet_setup_document_id: str) -> AggregationDocumentQuery[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------------------|----------------------------|-----------------------| +| **builder_or_facet** (Union) | `Callable[[FacetBuilder]`
**or**
`FacetBase` | Builder with a fluent API that constructs a `FacetBase` implementation instance
**or**
`FacetBase` implementation instance | +| **facets** | `List[FacetBase]` | A list of `FacetBase` implementations instances. | +| **facet_setup_document_id** | `str` | ID of a document containing `FacetSetup` | + + + + +{`class Facet(FacetBase): + def __init__(self, field_name: str = None): + super().__init__() + self.field_name = field_name +`} + + + + +{`class RangeFacet(FacetBase): + def __init__(self, parent: Optional[FacetBase] = None): + super().__init__() + self.ranges: List[str] = [] +`} + + + + +{`class FacetBase(ABC): + def __init__(self): + self.display_field_name: Union[None, str] = None + self.options: Union[None, FacetOptions] = None + self.aggregations: Dict[FacetAggregation, Set[FacetAggregationField]] = {} +`} + + + + +{`class FacetAggregation(enum.Enum): + NONE = "None" + MAX = "Max" + MIN = "Min" + AVERAGE = "Average" + SUM = "Sum" +`} + + + + +**Fluent API builder methods**: + + + +{`def by_ranges(self, range_: RangeBuilder, *ranges: RangeBuilder) -> FacetOperations[_T]: ... + +def by_field(self, field_name: str) -> FacetOperations[_T]: ... + +def with_display_name(self, display_name: str) -> FacetOperations[_T]: ... + +def with_options(self, options: FacetOptions) -> FacetOperations[_T]: ... + +def sum_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def min_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def max_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... + +def average_on(self, path: str, display_name: Optional[str] = None) -> FacetOperations[_T]: ... +`} + + + +| Parameter | Type | Description | +|------------------|-----------------------------|-------------| +| **range_** | `RangeBuilder` | A range of indexes | +| **\*ranges** | `RangeBuilder` | Multiple index ranges (at least one), separated by `,` | +| **field_name** | `str` | The index-field to use for the facet | +| **path** | `str` | Points to the index-field to use for the facet (`ByRanges`, `ByField`) or for the aggregation (`SUM_ON`, `MIN_ON`, `MAX_ON`, `AVERAGE_ON`) | +| **display_name** | `str` | If set, results of a facet will be returned under this name | +| **options** | `FacetOptions` | Non-default options to use in the facet definition | + + + +**Options**: + + + +{`class FacetOptions: + def __init__(self): + self.page_size: int = constants.int_max + self.start: Union[None, int] = None + self.term_sort_mode: FacetTermSortMode = FacetTermSortMode.VALUE_ASC + self.include_remaining_terms: bool = False +`} + + + +| Option | Type | Description | +|---------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| +| **term_sort_mode** | `FacetTermSortMode` | Set the sort order on the resulting items
(`VALUE_ASC` (Default), `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) | +| **start** | `int` | The position from which to send items (how many to skip) | +| **page_size** | `int` | Number of items to return | +| **include_remaining_terms** | `bool` | Indicates if remaining terms that didn't make it into the requested PageSize should be included in results
Default value: `False` | + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/_filtering-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_filtering-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_filtering-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_filtering-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_filtering-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_filtering-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_filtering-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_filtering-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_filtering-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_filtering-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_filtering-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_filtering-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_filtering-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_filtering-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_filtering-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_filtering-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_filtering-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_filtering-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_filtering-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_filtering-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_highlighting-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_highlighting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_highlighting-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_highlighting-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_highlighting-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_highlighting-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_highlighting-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_highlighting-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_highlighting-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_highlighting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_highlighting-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_highlighting-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_highlighting-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_highlighting-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_highlighting-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_highlighting-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_highlighting-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_highlighting-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_highlighting-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_highlighting-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_include-explanations-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_include-explanations-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_include-explanations-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_include-explanations-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_include-explanations-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_include-explanations-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_include-explanations-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_include-explanations-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_intersection-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_intersection-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_intersection-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_intersection-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_intersection-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_intersection-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_intersection-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_intersection-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_intersection-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_intersection-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_intersection-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_intersection-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_intersection-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_intersection-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_intersection-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_intersection-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_intersection-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_intersection-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_intersection-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_intersection-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_morelikethis-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_morelikethis-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_morelikethis-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_morelikethis-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_morelikethis-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_morelikethis-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_morelikethis-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_morelikethis-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_morelikethis-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_morelikethis-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_morelikethis-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_morelikethis-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_morelikethis-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_morelikethis-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_morelikethis-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_morelikethis-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_morelikethis-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_morelikethis-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_morelikethis-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_morelikethis-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/content/_paging-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_paging-csharp.mdx new file mode 100644 index 0000000000..8f8b1df9c8 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_paging-csharp.mdx @@ -0,0 +1,783 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +List allResults = session + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple query without paging: +// ============================== + +List allResults = await asyncSession + .Query() + .Where(x => x.UnitsInStock > 10) + .OfType() + .ToListAsync(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +List allResults = session.Advanced + .DocumentQuery() + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + .ToList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = await asyncSession + .Query() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToListAsync(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +List thirdPageResults = session.Advanced + .DocumentQuery() + // Get the query stats if you wish to know the TOTAL number of results + .Statistics(out QueryStatistics stats) + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .Skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .Take(10) + .ToList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +long totalResults = stats.TotalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + // Apply some filtering condition as needed + .Where(x => x.UnitsInStock > 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToListAsync(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +List pagedResults; +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + // Apply some filtering condition as needed + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Skip the number of results that were already fetched + .Skip(pageNumber * pageSize) + // Request to get 'pageSize' results + .Take(pageSize) + .ToList(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.Count > 0); // Fetch next results +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + // Define how many items to return + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .Where(x => x.UnitsInStock > 10) + .OfType() + // Define a projection + .Select(x => new ProjectedClass + { + Category = x.Category, + Supplier = x.Supplier + }) + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 10; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .WhereGreaterThan(x => x.UnitsInStock, 10) + .OfType() + // Define a projection + .SelectFields() + // Call Distinct to remove duplicate projected results + .Distinct() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.SkippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.Count; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`public class Products_ByUnitsInStock : AbstractIndexCreationTask +{ + public class IndexEntry + { + public int UnitsInStock { get; set; } + } + + public Products_ByUnitsInStock() + { + Map = products => from product in products + select new + { + UnitsInStock = product.UnitsInStock + }; + } +} +`} + + + + +{`public class ProjectedClass +{ + public string Category { get; set; } + public string Supplier { get; set; } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = await asyncSession + .Query() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToListAsync(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`List pagedResults; + +long totalResults = 0; +long skippedResults = 0; +int totalUniqueResults = 0; + +int pageNumber = 0; +int pageSize = 50; + +do +{ + pagedResults = session.Advanced + .DocumentQuery() + .Statistics(out QueryStatistics stats) + .OfType() + // Add the number of skipped results to the "start location" + .Skip((pageNumber * pageSize) + skippedResults) + .Take(pageSize) + .ToList(); + + totalResults = stats.TotalResults; + skippedResults += stats.SkippedResults; + totalUniqueResults += pagedResults.Count; + + pageNumber++; +} +while (pagedResults.Count > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +public class Orders_ByProductName : AbstractIndexCreationTask +{ + public class IndexEntry + { + public string ProductName { get; set; } + } + + public Orders_ByProductName() + { + Map = orders => + from order in orders + from line in order.Lines + select new IndexEntry + { + ProductName = line.ProductName + }; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_paging-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_paging-java.mdx new file mode 100644 index 0000000000..0e9fbc3606 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_paging-java.mdx @@ -0,0 +1,307 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `int.MaxValue` (2,147,483,647). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + +The queries below will return all the results available. + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .toList(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Basic paging: + +Let's assume that our page size is `10`, and we want to retrieve the 3rd page. To do this, we need to issue following query: + + + + +{`List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) // skip 2 pages worth of products + .take(10) // take up to 10 products + .toList(); // execute query +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Find total results count when paging: + +While paging, you sometimes need to know the exact number of results returned from the query. The Client API supports this explicitly: + + + + +{`Reference stats = new Reference(); + +List results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .whereGreaterThan("UnitsInStock", 10) + .skip(20) + .take(10) + .toList(); + +int totalResults = stats.value.getTotalResults(); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + + +While the query will return with just 10 results, `totalResults` will hold the total number of matching documents. + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `TotalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `SkippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `SkippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `TotalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `SkippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + SkippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 10; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + + results = session + .query(Product.class, Products_ByUnitsInStock.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .whereGreaterThan("UnitsInStock", 10) + .distinct() + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Products_ByUnitsInStock extends AbstractIndexCreationTask { + public Products_ByUnitsInStock() { + map = "docs.Products.Select(product => new {" + + " UnitsInStock = product.UnitsInStock" + + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct * +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`List results; +int pageNumber = 0; +int pageSize = 50; +int skippedResults = 0; +Reference stats = new Reference<>(); + +do { + results = session + .query(Order.class, Order_ByOrderLines_ProductName.class) + .statistics(stats) + .skip((pageNumber * pageSize) + skippedResults) + .take(pageSize) + .toList(); + + skippedResults += stats.value.getSkippedResults(); + pageNumber++; +} while (results.size() > 0); +`} + + + + +{`public static class Orders_ByOrderLines_ProductName extends AbstractIndexCreationTask { + public Orders_ByOrderLines_ProductName() { + map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" + + " Product = line.ProductName " + + "})"; + } +} +`} + + + + +{`from index "Order/ByOrderLines/ProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_paging-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_paging-nodejs.mdx new file mode 100644 index 0000000000..8f97f74d19 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_paging-nodejs.mdx @@ -0,0 +1,400 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, the server will default to `2,147,483,647` (equivalent to `int.MaxValue` in C#). + In such case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, indexes with more than `2,147,483,647` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +const allResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .whereGreaterThan("UnitsInStock", 10) + .all(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +// Define an output param for getting the query stats +let stats; + +const thirdPageResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Get the query stats if you wish to know the TOTAL number of results + .statistics(s => stats = s) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + .skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + .take(10) + .all(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +const totalResults = stats.totalResults; + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +const PAGE_SIZE = 10; +let pageNumber = 0; +let pagedResults; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + // Apply some filtering condition as needed + .whereGreaterThan("UnitsInStock", 10) + // Skip the number of results that were already fetched + .skip(pageNumber * PAGE_SIZE) + // Request to get 'pageSize' results + .take(PAGE_SIZE) + .all(); + + pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (pagedResults.length > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance +**Better performance**: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +**Performance hints**: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by the hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + +![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In those cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* In order to do proper paging in those scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 10; + +do { + pagedResults = await session + .query({ indexName: "Products/ByUnitsInStock" }) + .statistics(s => stats = s) + .whereGreaterThan("UnitsInStock", 10) + // Define a projection + .selectFields(["Category", "Supplier"]) + // Call Distinct to remove duplicate projected results + .distinct() + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + // Define how many items to return + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; // Number of total matching documents (includes duplicates) + skippedResults += stats.skippedResults; // Number of duplicate results that were skipped + totalUniqueResults += pagedResults.length; // Number of unique results returned in this server call + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to skip(). +`} + + + + +{`class Products_ByUnitsInStock extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => ({ + UnitsInStock: p.UnitsInStock + })); + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`let pagedResults; +let stats; + +let totalResults = 0; +let totalUniqueResults = 0; +let skippedResults = 0; + +let pageNumber = 0; +const PAGE_SIZE = 50; + +do { + pagedResults = await session + .query({ indexName: "Orders/ByProductName" }) + .statistics(s => stats = s) + // Add the number of skipped results to the "start location" + .skip((pageNumber * PAGE_SIZE) + skippedResults) + .take(PAGE_SIZE) + .all(); + + totalResults = stats.totalResults; + skippedResults += stats.skippedResults; + totalUniqueResults += pagedResults.length; + + pageNumber++; +} +while (pagedResults.length > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Orders", order => { + return order.Lines.map(line => { + return { + ProductName: line.ProductName + }; + }); + }); + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_paging-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_paging-php.mdx new file mode 100644 index 0000000000..9a3a910996 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_paging-php.mdx @@ -0,0 +1,688 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no-paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`// A simple query without paging: +// ============================== + +/** @var array $allResults */ +$allResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`// A simple DocumentQuery without paging: +// ====================================== + +/** @var array $allResults */ +$allResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + ->toList(); + +// Executing the query on the Northwind sample data +// will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats ) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`// Retrieve only the 3'rd page - when page size is 10: +// =================================================== + +$stats = new QueryStatistics(); + +/** @var array $thirdPageResults */ +$thirdPageResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Get the query stats if you wish to know the TOTAL number of results + ->statistics($stats) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Call 'Skip', pass the number of items to skip from the beginning of the result set + // Skip the first 20 resulting documents + ->skip(20) + // Call 'Take' to define the number of documents to return + // Take up to 10 products => so 10 is the "Page Size" + ->take(10) + ->toList(); + +// When executing this query on the Northwind sample data, +// results will include only 10 Product documents ("products/45-A" to "products/54-A") + +$totalResults = $stats->getTotalResults(); + +// While the query returns only 10 results, +// \`totalResults\` will hold the total number of matching documents (47). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`// Query for all results - page by page: +// ===================================== + +$pagedResults = null; +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + // Apply some filtering condition as needed + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Skip the number of results that were already fetched + ->skip($pageNumber * $pageSize) + // Request to get 'pageSize' results + ->take($pageSize) + ->toList(); + + $pageNumber++; + + // Make any processing needed with the current paged results here + // ... +} +while (count($pagedResults) > 0); // Fetch next results +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `totalResults` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skippedResults` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skippedResults` property from the stats object will hold the count of skipped (duplicate) results. + + * The `totalResults` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skippedResults` value when specifying the number of documents to skip for each page using: + `(currentPage * pageSize) + skippedResults`. + +## Examples + +#### A projection query with Distinct: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session + ->query(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + // Define how many items to return + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 10; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Products_ByUnitsInStock_IndexEntry::class, Products_ByUnitsInStock::class) + ->statistics($stats) + ->whereGreaterThan("UnitsInStock", 10) + ->ofType(Product::class) + // Define a projection + ->selectFields(ProjectedClass::class) + // Call Distinct to remove duplicate projected results + ->distinct() + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); // Number of total matching documents (includes duplicates) + $skippedResults += $stats->getSkippedResults(); // Number of duplicate results that were skipped + $totalUniqueResults += count($pagedResults); // Number of unique results returned in this server call + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total matching results reported in the stats is 47 (totalResults), +// but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +// due to the 'Distinct' usage which removes duplicates. + +// This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock_IndexEntry +{ + private ?int $unitsInStock = null; + + public function getUnitsInStock(): ?int + { + return $this->unitsInStock; + } + + public function setUnitsInStock(?int $unitsInStock): void + { + $this->unitsInStock = $unitsInStock; + } +} + +class Products_ByUnitsInStock extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Products.Select(product => new {" . + " UnitsInStock = product.UnitsInStock" . + "})"; + } +} +`} + + + + +{`class ProjectedClass +{ + public ?string $category = null; + public ?string $supplier = null; + + public function getCategory(): ?string + { + return $this->category; + } + + public function setCategory(?string $category): void + { + $this->category = $category; + } + + public function getSupplier(): ?string + { + return $this->supplier; + } + + public function setSupplier(?string $supplier): void + { + $this->supplier = $supplier; + } +} +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session + ->query(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`$pagedResults = null; + +$totalResults = 0; +$totalUniqueResults = 0; +$skippedResults = 0; + +$pageNumber = 0; +$pageSize = 50; + +do +{ + $pagedResults = $session->advanced() + ->documentQuery(Orders_ByProductName_IndexEntry::class, Orders_ByProductName::class) + ->statistics($stats) + ->ofType(Order::class) + // Add the number of skipped results to the "start location" + ->skip(($pageNumber * $pageSize) + $skippedResults) + ->take($pageSize) + ->toList(); + + $totalResults = $stats->getTotalResults(); + $skippedResults += $stats->getSkippedResults(); + $totalUniqueResults += count($pagedResults); + + $pageNumber++; +} +while (count($pagedResults) > 0); // Fetch next results + +// When executing the query on the Northwind sample data: +// ====================================================== + +// The total results reported in the stats is 2155 (totalResults), +// which represent the multiple index-entries generated as defined by the fanout index. + +// By adding the skipped results count to the Skip() method, +// we get the correct total unique results which is 830 Order documents. +`} + + + + +{`// A fanout index - creating MULTIPLE index-entries per document: +// ============================================================== + +class Orders_ByProductName_IndexEntry +{ + private ?string $productName = null; + + public function getProductName(): ?string + { + return $this->productName; + } + + public function setProductName(?string $productName): void + { + $this->productName = $productName; + } +} +class Orders_ByProductName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "docs.Orders.SelectMany(order => order.Lines, (order, line) => new {" . + " Product = line.ProductName " . + "})"; + } +} +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_paging-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_paging-python.mdx new file mode 100644 index 0000000000..a357c96094 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_paging-python.mdx @@ -0,0 +1,431 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* **Paging**: + Paging is the process of fetching a subset (a page) of results from a dataset, rather than retrieving the entire results at once. + This method enables processing query results one page at a time. + +* **Default page size**: + + * Querying **Lucene** indexes: + If the client's query definition does Not explicitly specify the page size, + the server will default to a C# `int.MaxValue` (2,147,483,647). + In such a case, all results will be returned in a single server call. + + * Querying **Corax** indexes: + The default page size is the same as the one employed by Lucene. + Note: when using [Corax](../../indexes/search-engine/corax.mdx) as the search engine, + indexes with more than a C# `int.MaxValue` entries can be created and used. + To match this capacity, queries over Corax indexes can skip a number of results that exceed this max value and take documents from that location. + +* **Performance**: + Using paging is beneficial when handling large result datasets, contributing to improved performance. + See [paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) here below. + +* In this page: + + * [No-paging example](../../indexes/querying/paging.mdx#no---paging-example) + * [Paging examples](../../indexes/querying/paging.mdx#paging-examples) + * [Paging and performance](../../indexes/querying/paging.mdx#paging-and-performance) + * [Paging through tampered results](../../indexes/querying/paging.mdx#paging-through-tampered-results) + + +## No-paging example + + + + +{`# A simple query without paging: +# ============================== +all_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .where_greater_than("units_in_stock", 10) + .of_type(Product) +) + +# Executing the query on the Northwind sample data +# will result in all 47 Product documents that match the query predicate. +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +`} + + + + + + +## Paging examples + +#### Retrieve a specific page: + + + + +{`# Retrieve only the 3'rd page - when page size is 10: +# =================================================== +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + # While the query below returns only 10 results, + # 'total_results' will hold the total number of matching documents (47). + +third_page_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Get the query stats if you wish to know the TOTAL number of results + .statistics(__stats_callback) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Call 'skip', pass the number of items to skip from the beginning of the result set + # Skip the first 20 resulting documents + .skip(20) + # Call 'take' to define the number of documents to return + # Take up to 10 products => so 10 is the "Page Size" + .take(10) +) + +en executing this query on the Northwind sample data, +sults will include only 10 Product documents ("products/45-A" to "products/54-A") + + store.open_session() as session: +# region paging_2_1 +# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 20, 10 // skip 20, take 10 +`} + + + +#### Page through all results: + + + + +{`# Query for all results - page by page: +# ===================================== +paged_results: List[Product] = [] +page_number = 0 +page_size = 10 + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + # Apply some filtering condition as needed + .where_greater_than("units_in_stock", 10).of_type(Product) + # Skip the number of results that were already fetched + .skip(page_number * page_size) + # Request to get 'page_size' results + .take(page_size) + ) + page_number += 1 + + if len(paged_results) == 0: + break + + # Make any processing needed with the current paged results here + # ... +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +limit 0, 10 // First loop will skip 0, take 10 + +// The next loops in the code will each generate the above RQL with an increased 'skip' value: +// limit 10, 10 +// limit 20, 10 +// limit 30, 10 +// ... +`} + + + + + + +## Paging and performance + +#### Better performance: + +It is recommended to explicitly set a page size when making a query that is expected to generate a significant number of results. +This practice has several benefits: + +* Optimizes bandwidth usage by reducing data transfer between the server and client. +* Prevents delays in response times caused by sending too much data over the network. +* Avoids high memory consumption when dealing with numerous documents. +* Ensures a more manageable user experience by not overwhelming users with massive datasets at once. +#### Performance hints: + +* By default, if the number of returned results exceeds **2048**, the server will issue a "Page size too big" notification (visible in the Studio) with information about the query. + +* This threshold can be customized by modifying the value of the [PerformanceHints.MaxNumberOfResults](../../server/configuration/performance-hints-configuration.mdx#performancehintsmaxnumberofresults) configuration key. + +* As suggested by this performance hint, you may consider using [Streaming query results](../../client-api/session/querying/how-to-stream-query-results.mdx) instead of paging. + + ![Figure 1. Performance Hint](../assets/performance-hint.png) + + + +## Paging through tampered results + +* The `QueryStatistics` object contains the `total_results` property, + which represents the total number of matching documents found in the query results. + +* The `QueryStatistics` object also contains the `skipped_results` property. + Whenever this property is greater than **0**, that implies the server has skipped that number of results from the index. + +* The server will skip duplicate results internally in the following two scenarios: + + 1. When making a [Projection query](../../indexes/querying/projections.mdx) with [Distinct](../../indexes/querying/distinct.mdx). + + 2. When querying a [Fanout index](../../indexes/indexing-nested-data.mdx#fanout-index---multiple-index-entries-per-document). + +* In these cases: + + * The `skipped_results` property from the stats object will hold the count of skipped (duplicate) results. + + * The `total_results` property will be invalidated - + it will Not deduct the number of skipped results from the total number of results. + +* To do proper paging in these scenarios: + include the `skipped_results` value when specifying the number of documents to skip for each page using: + `(current_page * page_size) + skipped_results`. + +## Examples + +#### A projection query with Distinct: + + + + +{`paged_results: List[ProjectedClass] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 10 + +def __stats_callback(statistics: QueryStatistics): + total_results = statistics.total_results + nonlocal skipped_results + skipped_results += statistics.skipped_results + +while True: + paged_results = list( + session.query_index_type(Products_ByUnitsInStock, Products_ByUnitsInStock.IndexEntry) + .statistics(__stats_callback) + .where_greater_than("units_in_stock", 10) + .of_type(Product) + # Define a projection + .select_fields(ProjectedClass) + # Call distinct to remove duplicate projected results + .distinct() + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total matching results reported in the stats is 47 (totalResults), +# but the total unique objects returned while paging the results is only 29 (totalUniqueResults) +# due to the 'Distinct' usage which removes duplicates. + +# This is solved by adding the skipped results count to Skip(). +`} + + + + +{`class Products_ByUnitsInStock(AbstractIndexCreationTask): + def __init__(self): + super().__init__() + self.map = "from product in docs.Products select new { units_in_stock = product.UnitsInStock }" + + class IndexEntry: + def __init__(self, units_in_stock: int = None): + self.units_in_stock = units_in_stock +`} + + + + +{`class ProjectedClass: + def __init__(self, category: str = None, supplier: str = None): + self.category = category + self.supplier = supplier + + # Handle different casing by implementing from_json class method + @classmethod + def from_json(cls, json_dict: Dict[str, Any]): + return cls(json_dict["Category"], json_dict["Supplier"]) +`} + + + + +{`from index "Products/ByUnitsInStock" +where UnitsInStock > 10 +select distinct Category, Supplier +limit 0, 10 // First loop will skip 0, take 10, etc. +`} + + + + +#### Querying a Fanout index: + + + + +{`paged_results: List[Order] = [] + +total_results = 0 +total_unique_results = 0 +skipped_results = 0 + +page_number = 0 +page_size = 50 + +def __stats_callback(statistics: QueryStatistics): + nonlocal skipped_results + skipped_results += statistics.skipped_results + total_results = statistics.total_results + +while True: + paged_results = list( + session.query_index_type(Orders_ByProductName, Orders_ByProductName.IndexEntry) + .statistics(__stats_callback) + .of_type(Order) + # Add the number of skipped results to the "start location" + .skip((page_size * page_size) + skipped_results) + .take(page_size) + ) + + total_unique_results += len(paged_results) + + if len(paged_results) == 0: + break + +# When executing the query on the Northwind sample data: +# ====================================================== + +# The total results reported in the stats is 2155 (total_results), +# which represent the multiple index-entries generated as defined by the fanout index. + +# By adding the skipped results count to the skip() method, +# we get the correct total unique results which is 830 Order documents. +`} + + + + +{`# A fanout index - creating MULTIPLE index-entries per document: +# ============================================================== +class Orders_ByProductName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + self.map = "from order in docs.Orders from line in order.Lines select new { product_name = line.ProductName }" +`} + + + + +{`from index "Orders/ByProductName" +limit 0, 50 // First loop will skip 0, take 50, etc. +`} + + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/_projections-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_projections-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_projections-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_projections-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_projections-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_projections-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_projections-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_projections-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_projections-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_projections-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_projections-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_projections-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_projections-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_projections-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_projections-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_projections-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_projections-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_projections-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_projections-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_projections-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_query-index-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_query-index-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_query-index-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_query-index-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_query-index-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_query-index-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_query-index-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_query-index-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_query-index-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_query-index-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_query-index-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_query-index-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_query-index-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_query-index-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_query-index-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_query-index-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_query-index-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_query-index-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_query-index-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_query-index-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_searching-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_searching-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_searching-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_searching-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_searching-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_searching-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_searching-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_searching-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_searching-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_searching-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_searching-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_searching-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_searching-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_searching-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_searching-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_searching-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_searching-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_searching-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_searching-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_searching-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_sorting-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_sorting-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_sorting-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_sorting-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_sorting-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_sorting-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_sorting-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_sorting-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_sorting-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_sorting-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_sorting-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_sorting-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_sorting-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_sorting-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_sorting-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_sorting-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_sorting-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_sorting-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_sorting-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_sorting-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_spatial-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_spatial-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_spatial-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_spatial-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/content/_spatial-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_spatial-java.mdx new file mode 100644 index 0000000000..42d7ef5ea6 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_spatial-java.mdx @@ -0,0 +1,121 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +To perform a spatial search, you can use the `spatial` method which contains a full spectrum of spatial capabilities. +You can check the detailed Client API reference for this method [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Radius Search + +The most basic usage and probably most common one is to search for all points or shapes within provided distance from the given center point. To perform this search use the `withinRadius` method. + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.circle(500, 30, 30)) +`} + + + + +## Advanced Search + +The most advanced (and low-level) method available is `relatesToShape` + + + + +{`List results = session + .query(Event.class) + .spatial(new PointField("latitude", "longitude"), + criteria -> criteria.relatesToShape( + "Circle(30 30 d=500.0000)", + SpatialRelation.WITHIN + )) + .toList(); +`} + + + + +{`from Events +where spatial.within(spatial.point(latitude, longitude), spatial.wkt('Circle(30 30 d=500.0000)')) +`} + + + + +Where the shape is in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format and the relation is one of `within`, `contains`, `disjoint`, `intersects`. The above example will yield the same results as the example from the `Radius Search` section. + + +When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed +in a counter-clockwise order: + + + +![NoSQL ACID DB - Query a Spatial Index](../assets/spatial_1.png) + + +## Static Indexes + +All of the above examples are using the dynamic querying capabilities of RavenDB and will create automatic indexes to retrieve their results. However, spatial queries can also be performed against static indexes, and this is done in a very similar way. + + + + +{`List results = session + .query(Event.class, Events_ByCoordinates.class) + .spatial("coordinates", + criteria -> criteria.withinRadius(500, 30, 30)) + .toList(); +`} + + + + +{`public static class Events_ByCoordinates extends AbstractIndexCreationTask { + public Events_ByCoordinates() { + map = "docs.Events.Select(e => new {" + + " Coordinates = this.CreateSpatialField(((double ? ) e.latitude), ((double ? ) e.longitude))" + + "})"; + } +} +`} + + + + +{`from index 'Events/ByCoordinates' +where spatial.within(coordinates, spatial.circle(500, 30, 30)) +`} + + + + + +If you want to know how to setup and customize a spatial field in static index please refer to [this](../../indexes/indexing-spatial-data.mdx) article. + + +## Ordering + +In order to sort the results by distance, please use the `orderByDistance` or `orderByDistanceDescending` methods. You can read more about them [here](../../client-api/session/querying/how-to-make-a-spatial-query.mdx). + +## Remarks + + +Distance in RavenDB by default is measured in **kilometers**. + + + diff --git a/versioned_docs/version-7.1/indexes/querying/_spatial-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_spatial-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_spatial-nodejs.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_spatial-nodejs.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_spatial-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_spatial-php.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_spatial-php.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_spatial-php.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/_spatial-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_spatial-python.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_spatial-python.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_spatial-python.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/content/_suggestions-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-csharp.mdx new file mode 100644 index 0000000000..5d414e3109 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-csharp.mdx @@ -0,0 +1,608 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`public class Products_ByName : AbstractIndexCreationTask +\{ + // The IndexEntry class defines the index-fields + public class IndexEntry + \{ + public string ProductName \{ get; set; \} + \} + + public Products_ByName() + \{ + // The 'Map' function defines the content of the index-fields + Map = products => from product in products + select new IndexEntry + \{ + ProductName = product.Name + \}; + + // Configure index-field 'ProductName' for suggestions + Suggestion(x => x.ProductName); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + Indexes.Add(x => x.ProductName, FieldIndexing.Search); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for single term +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +foreach (string suggestedTerm in suggestions["ProductName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request for multiple terms +var suggestionRequest = new SuggestionWithTerms("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + Terms = new[] { "chokolade", "syrop"} +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .ByField(x => x.ProductName, new[] { "chokolade", "syrop" })) + .Execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .ExecuteAsync(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +var request1 = new SuggestionWithTerm("CompanyName") +{ + // Looking for terms from index-field 'CompanyName' that are similar to 'chese' + Term = "chese" +}; + +var request2 = new SuggestionWithTerm("ContactName") +{ + // Looking for terms from nested index-field 'ContactName' that are similar to 'frank' + Term = "frank" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + .SuggestUsing(request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + .AndSuggestUsing(request2) + .Execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .SuggestUsing(builder => builder + .ByField(x => x.CompanyName, "chese" )) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .AndSuggestUsing(builder => builder + .ByField(x => x.ContactName, "frank")) + .Execute(); +`} + + + + +{`public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask +{ + // The IndexEntry class defines the index-fields. + public class IndexEntry + { + public string CompanyName { get; set; } + public string ContactName { get; set; } + } + + public Companies_ByNameAndByContactName() + { + // The 'Map' function defines the content of the index-fields + Map = companies => from company in companies + select new IndexEntry + { + CompanyName = company.Name, + ContactName = company.Contact.Name + }; + + // Configure the index-fields for suggestions + Suggestion(x => x.CompanyName); + Suggestion(x => x.ContactName); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + Indexes.Add(x => x.CompanyName, FieldIndexing.Search); + Indexes.Add(x => x.ContactName, FieldIndexing.Search); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .ExecuteAsync(); +`} + + + + +{`// Define the suggestion request +var suggestionRequest = new SuggestionWithTerm("ProductName") +{ + // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' + Term = "chokolade", + // Customize options + Options = new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }, + // Customize display name + DisplayField = "SomeCustomName" +}; + +// Query the index for suggestions +Dictionary suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + .ByField(x => x.ProductName, "chokolade") + // Customize suggestions options + .WithOptions(new SuggestionOptions + { + Accuracy = 0.3f, + PageSize = 5, + Distance = StringDistanceTypes.NGram, + SortMode = SuggestionSortMode.Popularity + }) + // Customize display name for results + .WithDisplayName("SomeCustomName")) + .Execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +Console.WriteLine("Suggested terms:"); +// Results are available under the custom name entry +foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions) +\{ + Console.WriteLine("\\t\{0\}", suggestedTerm); +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/_suggestions-java.mdx b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-java.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_suggestions-java.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_suggestions-java.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/content/_suggestions-nodejs.mdx b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-nodejs.mdx new file mode 100644 index 0000000000..c75a713f36 --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-nodejs.mdx @@ -0,0 +1,341 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName extends AbstractJavaScriptIndexCreationTask \{ + constructor() \{ + super(); + + this.map("Products", p => \{ + return \{ + ProductName: p.Name + \}; + \}); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the **Northwind sample data**, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the **Northwind sample data**, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +const products = await session + .query(\{ indexName: "Products/ByName" \}) + .search("ProductName", "chokolade") + .all(); +`} + + + +If you suspect that the term `chokolate` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); +suggestions["ProductName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); +`} + + + + +{`class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +console.log("Suggested terms:"); +// Results are available under the custom name entry +suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => \{ + console.log("\\t" + suggestedTerm); +\}); + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_suggestions-php.mdx b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-php.mdx new file mode 100644 index 0000000000..5ed5ae7f2b --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-php.mdx @@ -0,0 +1,585 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`// The IndexEntry class defines the index-fields +class Products_ByName_IndexEntry +\{ + private ?string $productName = null; + + public function getProductName(): ?string + \{ + return $this->productName; + \} + + public function setProductName(?string $productName): void + \{ + $this->productName = $productName; + \} +\} +class Products_ByName extends AbstractIndexCreationTask +\{ + public function __construct() + \{ + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map = "from product in docs.Products " . + "select new " . + "\{ " . + " product.Name " . + "\} "; + + // Configure index-field 'ProductName' for suggestions + $this->suggestion("Name"); // configuring suggestions + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + $this->index("Name", FieldIndexing::search()); // (optional) splitting name into multiple tokens + + \} +\} +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`// This query on index 'Products/ByName' has NO resulting documents +/** @var array $products */ +$products = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + ->search("ProductName", "chokolade") + ->ofType(Product::class) + ->toList(); +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function ($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for single term +$suggestionRequest = new SuggestionWithTerm("ProductName"); +$suggestionRequest->setTerm("chokolade"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->Execute(); +`} + + + + +{`// Query the index for suggested terms for single term: +// ==================================================== + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + return $builder->byField("ProductName", "chokolade"); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"; +foreach ($suggestions["ProductName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade': +// schokolade +// chocolade +// chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->ByField("ProductName", ["chokolade", "syrop"]); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request for multiple terms +$suggestionRequest = new SuggestionWithTerms("ProductName"); +$suggestionRequest->setTerms([ "chokolade", "syrop" ]); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms for multiple terms: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + return $builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + ->byField("ProductName", [ "chokolade", "syrop" ]); + }) + ->execute(); +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': +// schokolade +// chocolade +// chocolate +// sirop +// syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->byField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(functioN($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// Define suggestion requests for multiple fields: + +$request1 = new SuggestionWithTerm("CompanyName"); +// Looking for terms from index-field 'CompanyName' that are similar to 'chese' +$request1->setTerm("chese"); + +$request2 = new SuggestionWithTerm("ContactName"); +// Looking for terms from nested index-field 'ContactName' that are similar to 'frank' +$request2->setTerm("frank"); + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' - pass the suggestion request for the first index-field + ->suggestUsing($request1) + // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field + ->andSuggestUsing($request2) + ->execute(); +`} + + + + +{`// Query the index for suggested terms in multiple fields: +// ======================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Companies_ByNameAndByContactName_IndexEntry::class, Companies_ByNameAndByContactName::class) + // Call 'SuggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + ->suggestUsing(function($builder) { + return $builder + ->ByField("CompanyName", "chese" ); + }) + // Call 'AndSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + ->andSuggestUsing(function($builder) { + return $builder + ->byField("ContactName", "frank"); + }) + ->execute(); +`} + + + + +{`// The IndexEntry class defines the index-fields. +class Companies_ByNameAndByContactName_IndexEntry +{ + private ?string $companyName = null; + private ?string $contactName = null; + + public function getCompanyName(): ?string + { + return $this->companyName; + } + + public function setCompanyName(?string $companyName): void + { + $this->companyName = $companyName; + } + + public function getContactName(): ?string + { + return $this->contactName; + } + + public function setContactName(?string $contactName): void + { + $this->contactName = $contactName; + } +} + +class Companies_ByNameAndByContactName extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + // The 'Map' function defines the content of the index-fields + $this->map= "from company in docs.Companies" . + "select new { " . + "CompanyName = company.Name, " . + "ContactName = company.Contact.Name " . + "}"; + + // Configure the index-fields for suggestions + $this->suggestion("CompanyName"); + $this->suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + $this->index("CompanyName", FieldIndexing::search()); + $this->index("ContactName", FieldIndexing::search()); + } +} +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +// Suggested terms in index-field 'CompanyName' that is similar to 'chese': +// cheese +// chinese + +// Suggested terms in index-field 'ContactName' that are similar to 'frank': +// fran +// franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session + // Query the index + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $suggestionOptions = new SuggestionOptions(); + $suggestionOptions->setAccuracy(0.3); + $suggestionOptions->setPageSize(5); + $suggestionOptions->setDistance(StringDistanceTypes::nGram()); + $suggestionOptions->setSortMode(SuggestionSortMode::popularity()); + + $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($suggestionOptions) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Define the suggestion request +$suggestionRequest = new SuggestionWithTerm("ProductName"); +// Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +$suggestionRequest->setTerm("chokolade"); + +// Customize options +$options = new SuggestionOptions(); +$options->setAccuracy(0.3); +$options->setPageSize(5); +$options->setDistance(StringDistanceTypes::nGram()); +$options->setSortMode(SuggestionSortMode::popularity()); + +$suggestionRequest->setOptions($options); + +// Customize display name +$suggestionRequest->setDisplayField("SomeCustomName"); + + +// Query the index for suggestions +/** @var array $suggestions */ +$suggestions = $session + ->query(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' - pass the suggestion request + ->suggestUsing($suggestionRequest) + ->execute(); +`} + + + + +{`// Query the index for suggested terms - customize options and display name: +// ========================================================================= + +/** @var array $suggestions */ +$suggestions = $session->advanced() + // Query the index + ->documentQuery(Products_ByName_IndexEntry::class, Products_ByName::class) + // Call 'SuggestUsing' + ->suggestUsing(function($builder) { + $options = new SuggestionOptions(); + $options->setAccuracy(0.3); + $options->setPageSize(5); + $options->setDistance(StringDistanceTypes::nGram()); + $options->setSortMode(SuggestionSortMode::popularity()); + + return $builder + ->byField("ProductName", "chokolade") + // Customize suggestions options + ->withOptions($options) + // Customize display name for results + ->withDisplayName("SomeCustomName"); + }) + ->execute(); +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`// The resulting suggested terms: +// ============================== + +echo "Suggested terms:"; +// Results are available under the custom name entry +foreach ($suggestions["SomeCustomName"]->getSuggestions() as $suggestedTerm) +\{ + echo "\\t" . $suggestedTerm; +\} + +// Suggested terms: +// chocolade +// schokolade +// chocolate +// chowder +// marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/content/_suggestions-python.mdx b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-python.mdx new file mode 100644 index 0000000000..21ba4bf75e --- /dev/null +++ b/versioned_docs/version-7.1/indexes/querying/content/_suggestions-python.mdx @@ -0,0 +1,424 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Prior to reading this article, please refer to [query for suggestions](../../client-api/session/querying/how-to-work-with-suggestions.mdx) + for general knowledge about Suggestions and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions.mdx#syntax). + +* In this page: + * [Configure the index for suggestions](../../indexes/querying/suggestions.mdx#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions.mdx#the-index-terms) + * [Suggest terms - for a single term](../../indexes/querying/suggestions.mdx#suggest-terms---for-a-single-term) + * [Suggest terms - for multiple terms](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../indexes/querying/suggestions.mdx#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../indexes/querying/suggestions.mdx#suggest-terms---customize-options-and-display-name) + + +## Configure the index for suggestions + +* In order to be able to ask for suggested terms when querying an index field, + that field must first be configured for suggestions in the **index definition**. + +* See the following sample index: + (This index will be used in the examples ahead). + + + +{`class Products_ByName(AbstractIndexCreationTask): + # The IndexEntry class defines the index-fields + class IndexEntry: + def __init__(self, product_name: str = None): + self.product_name = product_name + + def __init__(self): + super().__init__() + # The 'map' function defines the content of the index-fields + self.map = "from product in docs.Products select new \{product_name = product.Name\}" + self._suggestion("product_name") + self._index("product_name", FieldIndexing.SEARCH) +`} + + + + + +**Increased indexing time**: + +* When configuring an index for suggestions, then during the indexing process, + in addition to the regular breakdown of the data into terms (tokenization), + RavenDB will scramble the terms to simulate common errors. + +* This can impact indexing speed but the cost of querying suggestions is Not impacted. + + + + + +## The index terms + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](../assets/index-terms.png) + +1. **The index-field name** - as defined in the index definition. + In this example the field name is `ProductName`. + +2. **The terms** that were generated for this index-field from the documents in the Products collection. + * The image shows a partial view out of the 163 terms in this list. + * The terms were generated by RavenDB's [default search analyzer](../../indexes/using-analyzers.mdx#ravendb) since full-text search was set on this field. + + + +## Suggest terms - for a single term + +Based on the Northwind sample data, +the following query on the index `Products/ByName` from above has no resulting documents, +since the term `chokolade` does Not exist in the index terms for index-field `ProductName`. + + + +{`# This query on index 'Products/ByName' has NO resulting documents +products = list( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + .search("product_name", "chokolade") + .of_type(Product) +) +`} + + + +If you suspect that the term `chokolade` in the query criteria is written incorrectly, +you can ask RavenDB to suggest similar terms from the index, as follows: + + + + +{`# Query the index for suggested terms for single term: +# ==================================================== + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .by_field("product_name", "chokolade") + ).execute() +) +`} + + + + +{`# Define the suggestion request for single term +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' +suggestion_request.term = "chokolade" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms in index-field 'product_name' that are similar to 'chokolade':") +for suggested_term in suggestions["product_name"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade': +# schokolade +# chocolade +# chocolate +`} + + + + + +## Suggest terms - for multiple terms + + + + +{`# Query the index for suggested terms for multiple terms: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder + # Request to get terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' + .by_field("product_name", ["chokolade", "syrop"]) + ).execute() +) +`} + + + + +{`# Define the suggestion request for multiple terms +suggestion_request = SuggestionWithTerms("product_name") +# Looking for terms from index-field 'product_name' that are similar to 'chokolade' OR 'syrop' +suggestion_request.terms = ["chokolade", "syrop"] + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' +from index "Products/ByName" select suggest(ProductName, $p0) +{ "p0" : ["chokolade", "syrop"] } +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'product_name' that are similar to 'chokolade' OR to 'syrop': +# schokolade +# chocolade +# chocolate +# sirop +# syrup +`} + + + + + +## Suggest terms - for multiple fields + + + + +{`# Query the index for suggested terms in multiple fields: +# ======================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry) + # Call 'suggest_using' to get suggestions for terms that are + # similar to 'chese' in first index-field (e.g. 'company_name') + .suggest_using(lambda builder: builder.by_field("company_name", "chese")) + # Call 'and_suggest_using' to get suggestions for terms that are + # similar to 'frank' in an additional index-field (e.g. 'company_name') + .and_suggest_using(lambda builder: builder.by_field("contact_name", "frank")).execute() +) +`} + + + + +{`# Define suggestion requests for multiple fields: + +request1 = SuggestionWithTerm("company_name") +# Looking for terms from index-field 'company_name' that are similar to 'chese' +request1.term = "chese" + +request2 = SuggestionWithTerm("contact_name") +# Looking for terms from nested index-field 'contact_name' that are similar to 'frank' +request2.term = "frank" + +# Query the index for suggestions +suggestions = ( + session.query_index_type( + Companies_ByNameAndByContactName, Companies_ByNameAndByContactName.IndexEntry + ) + # Call 'suggest_using' - pass the suggestion request for the first index-field + .suggest_using(request1) + # Call 'and_suggest_using' - pass the suggestion request for the second index-field + .and_suggest_using(request2).execute() +) +`} + + + + +{`class Companies_ByNameAndByContactName(AbstractIndexCreationTask): + class IndexEntry: + def __init__(self, company_name: str = None, contact_name: str = None): + self.company_name = company_name + self.contact_name = contact_name + + def __init__(self): + super().__init__() + self.map = "from company in docs.Companies select new {company_name = company.Name, contact_name = company.Contact.Name}" + + # Configure the index-fields for suggestions + self._suggestion("company_name") + self._suggestion("contact_name") + + # Optionally: set 'search' on the index-fields + # This will split the fields' content into multiple terms allowing for a full-text search + self._index("company_name", FieldIndexing.SEARCH) + self._index("contact_name", FieldIndexing.SEARCH) +`} + + + + +{`// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +# Suggested terms in index-field 'company_name' that is similar to 'chese': +# cheese +# chinese + +# Suggested terms in index-field 'contact_name' that are similar to 'frank': +# fran +# franken +`} + + + + + +## Suggest terms - customize options and display name + + + + +{`# Query the index for suggested terms - customize options and display name: +# ========================================================================= + +suggestions = ( + session + # Query the index + .query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' + .suggest_using( + lambda builder: builder.by_field("product_name", "chokolade") + # Customize suggestions options + .with_options( + SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, + ) + ) + # Customize display name for results + .with_display_name("SomeCustomName") + ).execute() +) +`} + + + + +{`# Define the suggestion request +suggestion_request = SuggestionWithTerm("product_name") +# Looking for terms from index-field 'ProductName' that are similar to 'chokolade' +suggestion_request.term = "chokolade" +# Customize options +suggestion_request.options = SuggestionOptions( + accuracy=0.3, + page_size=5, + distance=StringDistanceTypes.N_GRAM, + sort_mode=SuggestionSortMode.POPULARITY, +) +# Customize display name +suggestion_request.display_field = "SomeCustomName" + +# Query the index for suggestions +suggestions = ( + session.query_index_type(Products_ByName, Products_ByName.IndexEntry) + # Call 'suggest_using' - pass the suggestion request + .suggest_using(suggestion_request).execute() +) +`} + + + + +{`// Query for suggested terms - customize options and display name +from index "Products/ByName" +select suggest( + ProductName, + "chokolade", + '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }' +) as "SomeCustomName" +`} + + + + + + +{`# The resulting suggested terms: +# ============================== + +print("Suggested terms:") +# Results are available under the custom name entry +for suggested_term in suggestions["SomeCustomName"].suggestions: + print(f"\\t\{suggested_term\}") + +# Suggested terms: +# chocolade +# schokolade +# chocolate +# chowder +# marmalade +`} + + + + + + diff --git a/versioned_docs/version-7.1/indexes/querying/_vector-search-csharp.mdx b/versioned_docs/version-7.1/indexes/querying/content/_vector-search-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/indexes/querying/_vector-search-csharp.mdx rename to versioned_docs/version-7.1/indexes/querying/content/_vector-search-csharp.mdx diff --git a/versioned_docs/version-7.1/indexes/querying/distinct.mdx b/versioned_docs/version-7.1/indexes/querying/distinct.mdx index fdffbb6014..4b054b58ef 100644 --- a/versioned_docs/version-7.1/indexes/querying/distinct.mdx +++ b/versioned_docs/version-7.1/indexes/querying/distinct.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DistinctCsharp from './_distinct-csharp.mdx'; -import DistinctJava from './_distinct-java.mdx'; -import DistinctNodejs from './_distinct-nodejs.mdx'; +import DistinctCsharp from './content/_distinct-csharp.mdx'; +import DistinctJava from './content/_distinct-java.mdx'; +import DistinctNodejs from './content/_distinct-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/exploration-queries.mdx b/versioned_docs/version-7.1/indexes/querying/exploration-queries.mdx index b15d5d7eb0..3cb4eae8b3 100644 --- a/versioned_docs/version-7.1/indexes/querying/exploration-queries.mdx +++ b/versioned_docs/version-7.1/indexes/querying/exploration-queries.mdx @@ -8,10 +8,10 @@ supported_languages: ["csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExplorationQueriesCsharp from './_exploration-queries-csharp.mdx'; -import ExplorationQueriesPython from './_exploration-queries-python.mdx'; -import ExplorationQueriesPhp from './_exploration-queries-php.mdx'; -import ExplorationQueriesNodejs from './_exploration-queries-nodejs.mdx'; +import ExplorationQueriesCsharp from './content/_exploration-queries-csharp.mdx'; +import ExplorationQueriesPython from './content/_exploration-queries-python.mdx'; +import ExplorationQueriesPhp from './content/_exploration-queries-php.mdx'; +import ExplorationQueriesNodejs from './content/_exploration-queries-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/faceted-search.mdx b/versioned_docs/version-7.1/indexes/querying/faceted-search.mdx index 5a15106f12..239cce3000 100644 --- a/versioned_docs/version-7.1/indexes/querying/faceted-search.mdx +++ b/versioned_docs/version-7.1/indexes/querying/faceted-search.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FacetedSearchCsharp from './_faceted-search-csharp.mdx'; -import FacetedSearchJava from './_faceted-search-java.mdx'; -import FacetedSearchPython from './_faceted-search-python.mdx'; -import FacetedSearchPhp from './_faceted-search-php.mdx'; -import FacetedSearchNodejs from './_faceted-search-nodejs.mdx'; +import FacetedSearchCsharp from './content/_faceted-search-csharp.mdx'; +import FacetedSearchJava from './content/_faceted-search-java.mdx'; +import FacetedSearchPython from './content/_faceted-search-python.mdx'; +import FacetedSearchPhp from './content/_faceted-search-php.mdx'; +import FacetedSearchNodejs from './content/_faceted-search-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/filtering.mdx b/versioned_docs/version-7.1/indexes/querying/filtering.mdx index 079775c637..2530bb9552 100644 --- a/versioned_docs/version-7.1/indexes/querying/filtering.mdx +++ b/versioned_docs/version-7.1/indexes/querying/filtering.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import FilteringCsharp from './_filtering-csharp.mdx'; -import FilteringJava from './_filtering-java.mdx'; -import FilteringPython from './_filtering-python.mdx'; -import FilteringPhp from './_filtering-php.mdx'; -import FilteringNodejs from './_filtering-nodejs.mdx'; +import FilteringCsharp from './content/_filtering-csharp.mdx'; +import FilteringJava from './content/_filtering-java.mdx'; +import FilteringPython from './content/_filtering-python.mdx'; +import FilteringPhp from './content/_filtering-php.mdx'; +import FilteringNodejs from './content/_filtering-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/highlighting.mdx b/versioned_docs/version-7.1/indexes/querying/highlighting.mdx index 6682f13aaf..566589aeaf 100644 --- a/versioned_docs/version-7.1/indexes/querying/highlighting.mdx +++ b/versioned_docs/version-7.1/indexes/querying/highlighting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import HighlightingCsharp from './_highlighting-csharp.mdx'; -import HighlightingJava from './_highlighting-java.mdx'; -import HighlightingPython from './_highlighting-python.mdx'; -import HighlightingPhp from './_highlighting-php.mdx'; -import HighlightingNodejs from './_highlighting-nodejs.mdx'; +import HighlightingCsharp from './content/_highlighting-csharp.mdx'; +import HighlightingJava from './content/_highlighting-java.mdx'; +import HighlightingPython from './content/_highlighting-python.mdx'; +import HighlightingPhp from './content/_highlighting-php.mdx'; +import HighlightingNodejs from './content/_highlighting-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/include-explanations.mdx b/versioned_docs/version-7.1/indexes/querying/include-explanations.mdx index 76c425b8f3..70b31a8871 100644 --- a/versioned_docs/version-7.1/indexes/querying/include-explanations.mdx +++ b/versioned_docs/version-7.1/indexes/querying/include-explanations.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IncludeExplanationsCsharp from './_include-explanations-csharp.mdx'; -import IncludeExplanationsNodejs from './_include-explanations-nodejs.mdx'; +import IncludeExplanationsCsharp from './content/_include-explanations-csharp.mdx'; +import IncludeExplanationsNodejs from './content/_include-explanations-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/intersection.mdx b/versioned_docs/version-7.1/indexes/querying/intersection.mdx index 7f865313ad..f5754e1f24 100644 --- a/versioned_docs/version-7.1/indexes/querying/intersection.mdx +++ b/versioned_docs/version-7.1/indexes/querying/intersection.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import IntersectionCsharp from './_intersection-csharp.mdx'; -import IntersectionJava from './_intersection-java.mdx'; -import IntersectionPython from './_intersection-python.mdx'; -import IntersectionPhp from './_intersection-php.mdx'; -import IntersectionNodejs from './_intersection-nodejs.mdx'; +import IntersectionCsharp from './content/_intersection-csharp.mdx'; +import IntersectionJava from './content/_intersection-java.mdx'; +import IntersectionPython from './content/_intersection-python.mdx'; +import IntersectionPhp from './content/_intersection-php.mdx'; +import IntersectionNodejs from './content/_intersection-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/morelikethis.mdx b/versioned_docs/version-7.1/indexes/querying/morelikethis.mdx index 6ff74498b1..32400ea815 100644 --- a/versioned_docs/version-7.1/indexes/querying/morelikethis.mdx +++ b/versioned_docs/version-7.1/indexes/querying/morelikethis.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import MorelikethisCsharp from './_morelikethis-csharp.mdx'; -import MorelikethisJava from './_morelikethis-java.mdx'; -import MorelikethisPython from './_morelikethis-python.mdx'; -import MorelikethisPhp from './_morelikethis-php.mdx'; -import MorelikethisNodejs from './_morelikethis-nodejs.mdx'; +import MorelikethisCsharp from './content/_morelikethis-csharp.mdx'; +import MorelikethisJava from './content/_morelikethis-java.mdx'; +import MorelikethisPython from './content/_morelikethis-python.mdx'; +import MorelikethisPhp from './content/_morelikethis-php.mdx'; +import MorelikethisNodejs from './content/_morelikethis-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/paging.mdx b/versioned_docs/version-7.1/indexes/querying/paging.mdx index 62287efa6c..9f42a98dbd 100644 --- a/versioned_docs/version-7.1/indexes/querying/paging.mdx +++ b/versioned_docs/version-7.1/indexes/querying/paging.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import PagingCsharp from './_paging-csharp.mdx'; -import PagingJava from './_paging-java.mdx'; -import PagingPython from './_paging-python.mdx'; -import PagingPhp from './_paging-php.mdx'; -import PagingNodejs from './_paging-nodejs.mdx'; +import PagingCsharp from './content/_paging-csharp.mdx'; +import PagingJava from './content/_paging-java.mdx'; +import PagingPython from './content/_paging-python.mdx'; +import PagingPhp from './content/_paging-php.mdx'; +import PagingNodejs from './content/_paging-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/projections.mdx b/versioned_docs/version-7.1/indexes/querying/projections.mdx index 6a24194fc0..779a07b48b 100644 --- a/versioned_docs/version-7.1/indexes/querying/projections.mdx +++ b/versioned_docs/version-7.1/indexes/querying/projections.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ProjectionsCsharp from './_projections-csharp.mdx'; -import ProjectionsJava from './_projections-java.mdx'; -import ProjectionsPython from './_projections-python.mdx'; -import ProjectionsPhp from './_projections-php.mdx'; -import ProjectionsNodejs from './_projections-nodejs.mdx'; +import ProjectionsCsharp from './content/_projections-csharp.mdx'; +import ProjectionsJava from './content/_projections-java.mdx'; +import ProjectionsPython from './content/_projections-python.mdx'; +import ProjectionsPhp from './content/_projections-php.mdx'; +import ProjectionsNodejs from './content/_projections-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/query-index.mdx b/versioned_docs/version-7.1/indexes/querying/query-index.mdx index 7cef287594..cbe9254808 100644 --- a/versioned_docs/version-7.1/indexes/querying/query-index.mdx +++ b/versioned_docs/version-7.1/indexes/querying/query-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import QueryIndexCsharp from './_query-index-csharp.mdx'; -import QueryIndexJava from './_query-index-java.mdx'; -import QueryIndexPython from './_query-index-python.mdx'; -import QueryIndexPhp from './_query-index-php.mdx'; -import QueryIndexNodejs from './_query-index-nodejs.mdx'; +import QueryIndexCsharp from './content/_query-index-csharp.mdx'; +import QueryIndexJava from './content/_query-index-java.mdx'; +import QueryIndexPython from './content/_query-index-python.mdx'; +import QueryIndexPhp from './content/_query-index-php.mdx'; +import QueryIndexNodejs from './content/_query-index-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/searching.mdx b/versioned_docs/version-7.1/indexes/querying/searching.mdx index 9f0b5aebc1..9b88c79e82 100644 --- a/versioned_docs/version-7.1/indexes/querying/searching.mdx +++ b/versioned_docs/version-7.1/indexes/querying/searching.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SearchingCsharp from './_searching-csharp.mdx'; -import SearchingJava from './_searching-java.mdx'; -import SearchingPython from './_searching-python.mdx'; -import SearchingPhp from './_searching-php.mdx'; -import SearchingNodejs from './_searching-nodejs.mdx'; +import SearchingCsharp from './content/_searching-csharp.mdx'; +import SearchingJava from './content/_searching-java.mdx'; +import SearchingPython from './content/_searching-python.mdx'; +import SearchingPhp from './content/_searching-php.mdx'; +import SearchingNodejs from './content/_searching-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/sorting.mdx b/versioned_docs/version-7.1/indexes/querying/sorting.mdx index d6d20340a8..5e0b1f7aa4 100644 --- a/versioned_docs/version-7.1/indexes/querying/sorting.mdx +++ b/versioned_docs/version-7.1/indexes/querying/sorting.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingCsharp from './_sorting-csharp.mdx'; -import SortingJava from './_sorting-java.mdx'; -import SortingPython from './_sorting-python.mdx'; -import SortingPhp from './_sorting-php.mdx'; -import SortingNodejs from './_sorting-nodejs.mdx'; +import SortingCsharp from './content/_sorting-csharp.mdx'; +import SortingJava from './content/_sorting-java.mdx'; +import SortingPython from './content/_sorting-python.mdx'; +import SortingPhp from './content/_sorting-php.mdx'; +import SortingNodejs from './content/_sorting-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/spatial.mdx b/versioned_docs/version-7.1/indexes/querying/spatial.mdx index a37b785d28..a014eac4b8 100644 --- a/versioned_docs/version-7.1/indexes/querying/spatial.mdx +++ b/versioned_docs/version-7.1/indexes/querying/spatial.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "python", "php", "nodejs", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SpatialCsharp from './_spatial-csharp.mdx'; -import SpatialPython from './_spatial-python.mdx'; -import SpatialPhp from './_spatial-php.mdx'; -import SpatialNodejs from './_spatial-nodejs.mdx'; -import SpatialJava from './_spatial-java.mdx'; +import SpatialCsharp from './content/_spatial-csharp.mdx'; +import SpatialPython from './content/_spatial-python.mdx'; +import SpatialPhp from './content/_spatial-php.mdx'; +import SpatialNodejs from './content/_spatial-nodejs.mdx'; +import SpatialJava from './content/_spatial-java.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/suggestions.mdx b/versioned_docs/version-7.1/indexes/querying/suggestions.mdx index 683d682fc1..b5a9efae03 100644 --- a/versioned_docs/version-7.1/indexes/querying/suggestions.mdx +++ b/versioned_docs/version-7.1/indexes/querying/suggestions.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "csharp", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SuggestionsJava from './_suggestions-java.mdx'; -import SuggestionsCsharp from './_suggestions-csharp.mdx'; -import SuggestionsPython from './_suggestions-python.mdx'; -import SuggestionsPhp from './_suggestions-php.mdx'; -import SuggestionsNodejs from './_suggestions-nodejs.mdx'; +import SuggestionsJava from './content/_suggestions-java.mdx'; +import SuggestionsCsharp from './content/_suggestions-csharp.mdx'; +import SuggestionsPython from './content/_suggestions-python.mdx'; +import SuggestionsPhp from './content/_suggestions-php.mdx'; +import SuggestionsNodejs from './content/_suggestions-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/querying/vector-search.mdx b/versioned_docs/version-7.1/indexes/querying/vector-search.mdx index 696138dc56..2d9834abaa 100644 --- a/versioned_docs/version-7.1/indexes/querying/vector-search.mdx +++ b/versioned_docs/version-7.1/indexes/querying/vector-search.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import VectorSearchCsharp from './_vector-search-csharp.mdx'; +import VectorSearchCsharp from './content/_vector-search-csharp.mdx'; diff --git a/versioned_docs/version-7.1/indexes/sorting-and-collation.mdx b/versioned_docs/version-7.1/indexes/sorting-and-collation.mdx index a2b483621a..2c938b321e 100644 --- a/versioned_docs/version-7.1/indexes/sorting-and-collation.mdx +++ b/versioned_docs/version-7.1/indexes/sorting-and-collation.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import SortingAndCollationCsharp from './_sorting-and-collation-csharp.mdx'; -import SortingAndCollationJava from './_sorting-and-collation-java.mdx'; +import SortingAndCollationCsharp from './content/_sorting-and-collation-csharp.mdx'; +import SortingAndCollationJava from './content/_sorting-and-collation-java.mdx'; diff --git a/versioned_docs/version-7.1/indexes/stale-indexes.mdx b/versioned_docs/version-7.1/indexes/stale-indexes.mdx index 5d8836abc5..a75a9cacc8 100644 --- a/versioned_docs/version-7.1/indexes/stale-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/stale-indexes.mdx @@ -8,9 +8,9 @@ supported_languages: ["csharp", "java", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StaleIndexesCsharp from './_stale-indexes-csharp.mdx'; -import StaleIndexesJava from './_stale-indexes-java.mdx'; -import StaleIndexesNodejs from './_stale-indexes-nodejs.mdx'; +import StaleIndexesCsharp from './content/_stale-indexes-csharp.mdx'; +import StaleIndexesJava from './content/_stale-indexes-java.mdx'; +import StaleIndexesNodejs from './content/_stale-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/storing-data-in-index.mdx b/versioned_docs/version-7.1/indexes/storing-data-in-index.mdx index cb28e5c4f7..e0a7569775 100644 --- a/versioned_docs/version-7.1/indexes/storing-data-in-index.mdx +++ b/versioned_docs/version-7.1/indexes/storing-data-in-index.mdx @@ -8,11 +8,11 @@ supported_languages: ["java", "python", "php", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import StoringDataInIndexJava from './_storing-data-in-index-java.mdx'; -import StoringDataInIndexPython from './_storing-data-in-index-python.mdx'; -import StoringDataInIndexPhp from './_storing-data-in-index-php.mdx'; -import StoringDataInIndexNodejs from './_storing-data-in-index-nodejs.mdx'; -import StoringDataInIndexCsharp from './_storing-data-in-index-csharp.mdx'; +import StoringDataInIndexJava from './content/_storing-data-in-index-java.mdx'; +import StoringDataInIndexPython from './content/_storing-data-in-index-python.mdx'; +import StoringDataInIndexPhp from './content/_storing-data-in-index-php.mdx'; +import StoringDataInIndexNodejs from './content/_storing-data-in-index-nodejs.mdx'; +import StoringDataInIndexCsharp from './content/_storing-data-in-index-csharp.mdx'; diff --git a/versioned_docs/version-7.1/indexes/using-analyzers.mdx b/versioned_docs/version-7.1/indexes/using-analyzers.mdx index bfaac039c9..0993e74dc7 100644 --- a/versioned_docs/version-7.1/indexes/using-analyzers.mdx +++ b/versioned_docs/version-7.1/indexes/using-analyzers.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingAnalyzersJava from './_using-analyzers-java.mdx'; -import UsingAnalyzersCsharp from './_using-analyzers-csharp.mdx'; -import UsingAnalyzersNodejs from './_using-analyzers-nodejs.mdx'; +import UsingAnalyzersJava from './content/_using-analyzers-java.mdx'; +import UsingAnalyzersCsharp from './content/_using-analyzers-csharp.mdx'; +import UsingAnalyzersNodejs from './content/_using-analyzers-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/using-dynamic-fields.mdx b/versioned_docs/version-7.1/indexes/using-dynamic-fields.mdx index d04eae405e..194c98923e 100644 --- a/versioned_docs/version-7.1/indexes/using-dynamic-fields.mdx +++ b/versioned_docs/version-7.1/indexes/using-dynamic-fields.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingDynamicFieldsCsharp from './_using-dynamic-fields-csharp.mdx'; -import UsingDynamicFieldsJava from './_using-dynamic-fields-java.mdx'; -import UsingDynamicFieldsPython from './_using-dynamic-fields-python.mdx'; -import UsingDynamicFieldsPhp from './_using-dynamic-fields-php.mdx'; -import UsingDynamicFieldsNodejs from './_using-dynamic-fields-nodejs.mdx'; +import UsingDynamicFieldsCsharp from './content/_using-dynamic-fields-csharp.mdx'; +import UsingDynamicFieldsJava from './content/_using-dynamic-fields-java.mdx'; +import UsingDynamicFieldsPython from './content/_using-dynamic-fields-python.mdx'; +import UsingDynamicFieldsPhp from './content/_using-dynamic-fields-php.mdx'; +import UsingDynamicFieldsNodejs from './content/_using-dynamic-fields-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/indexes/using-term-vectors.mdx b/versioned_docs/version-7.1/indexes/using-term-vectors.mdx index 48af4fb751..dfbd9448bb 100644 --- a/versioned_docs/version-7.1/indexes/using-term-vectors.mdx +++ b/versioned_docs/version-7.1/indexes/using-term-vectors.mdx @@ -8,9 +8,9 @@ supported_languages: ["java", "nodejs", "csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import UsingTermVectorsJava from './_using-term-vectors-java.mdx'; -import UsingTermVectorsNodejs from './_using-term-vectors-nodejs.mdx'; -import UsingTermVectorsCsharp from './_using-term-vectors-csharp.mdx'; +import UsingTermVectorsJava from './content/_using-term-vectors-java.mdx'; +import UsingTermVectorsNodejs from './content/_using-term-vectors-nodejs.mdx'; +import UsingTermVectorsCsharp from './content/_using-term-vectors-csharp.mdx'; diff --git a/versioned_docs/version-7.1/indexes/what-are-indexes.mdx b/versioned_docs/version-7.1/indexes/what-are-indexes.mdx index b05d8422dc..8821d797d4 100644 --- a/versioned_docs/version-7.1/indexes/what-are-indexes.mdx +++ b/versioned_docs/version-7.1/indexes/what-are-indexes.mdx @@ -8,11 +8,11 @@ supported_languages: ["csharp", "java", "python", "php", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import WhatAreIndexesCsharp from './_what-are-indexes-csharp.mdx'; -import WhatAreIndexesJava from './_what-are-indexes-java.mdx'; -import WhatAreIndexesPython from './_what-are-indexes-python.mdx'; -import WhatAreIndexesPhp from './_what-are-indexes-php.mdx'; -import WhatAreIndexesNodejs from './_what-are-indexes-nodejs.mdx'; +import WhatAreIndexesCsharp from './content/_what-are-indexes-csharp.mdx'; +import WhatAreIndexesJava from './content/_what-are-indexes-java.mdx'; +import WhatAreIndexesPython from './content/_what-are-indexes-python.mdx'; +import WhatAreIndexesPhp from './content/_what-are-indexes-php.mdx'; +import WhatAreIndexesNodejs from './content/_what-are-indexes-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/server/_embedded-csharp.mdx b/versioned_docs/version-7.1/server/content/_embedded-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/server/_embedded-csharp.mdx rename to versioned_docs/version-7.1/server/content/_embedded-csharp.mdx diff --git a/versioned_docs/version-7.1/server/_embedded-java.mdx b/versioned_docs/version-7.1/server/content/_embedded-java.mdx similarity index 100% rename from versioned_docs/version-7.1/server/_embedded-java.mdx rename to versioned_docs/version-7.1/server/content/_embedded-java.mdx diff --git a/versioned_docs/version-7.1/server/embedded.mdx b/versioned_docs/version-7.1/server/embedded.mdx index 4edae5bf13..6f8c63988c 100644 --- a/versioned_docs/version-7.1/server/embedded.mdx +++ b/versioned_docs/version-7.1/server/embedded.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import EmbeddedCsharp from './_embedded-csharp.mdx'; -import EmbeddedJava from './_embedded-java.mdx'; +import EmbeddedCsharp from './content/_embedded-csharp.mdx'; +import EmbeddedJava from './content/_embedded-java.mdx'; diff --git a/versioned_docs/version-7.1/server/extensions/_refresh-csharp.mdx b/versioned_docs/version-7.1/server/extensions/_refresh-csharp.mdx deleted file mode 100644 index 851e395d08..0000000000 --- a/versioned_docs/version-7.1/server/extensions/_refresh-csharp.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), - triggering its re-indexation as well as other features that react to document updates. - -* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). - -* In this page: - * [Overview](../../server/extensions/refresh.mdx#overview) - * [Examples](../../server/extensions/refresh.mdx#examples) - * [Syntax](../../server/extensions/refresh.mdx#syntax) - * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) - - - -## Overview - -* To set a document refresh time, add the document's `@metadata` a - `@refresh` property with the designated refresh time as a value. - Set the time in **UTC** format, not local time, e.g. - - **"@refresh": "2025-04-22T08:00:00.0000000Z"** - - Metadata properties starting with `@` are for internal RavenDB usage only. - Do _not_ use the metadata `@refresh` property for any other purpose than - scheduling a document's refresh time for the built-in refresh feature. - - -* This will cause the document to refresh **only once**. - When the refresh operation takes place, it will also remove the `@refresh` property from the document. - - - 1. The refresh time value set for the `@refresh` property. - 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), - including - - - The interval by which the server refreshes documents (set by default to 60 seconds). - - The way you set **maximal items to process**, potentially limiting the number - of documents that RavenDB is allowed to delete each time the refresh feature is invoked. - - - -* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) - to increment the same way it would after any other kind of update to the document. - This triggers any features that react to document updating, including but not limited to: - - Re-indexing of the document by indexes that cover it - - [Replication](../../server/ongoing-tasks/external-replication.mdx), - [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), - and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering - - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) - - - -## Examples - -#### Example I - -How to set refresh configuration for a database: - - - -{`var refreshConfig = new RefreshConfiguration \{ - Disabled = false, - RefreshFrequencyInSec = 300, - MaxItemsToProcess = 1000 -\}; - -var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); -`} - - - -This activates document refreshing and sets the interval at 5 minutes. - - -#### Example II - -How to set a document to refresh 1 hour from now: - - - -{`using (var session = documentStore.OpenSession()) -\{ - var document = session.Load("users/1-A"); - - session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); - - session.SaveChanges(); -\} -`} - - - - - -## Syntax - -To activate and/or configure document refreshing, send the server a -`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. -#### `RefreshConfiguration` - - - -{`public class RefreshConfiguration -\{ - // Set 'Disabled' to false to enable the refresh feature - public bool Disabled \{ get; set; \} - - // How frequently to process documents with a @refresh flag - public long? RefreshFrequencyInSec \{ get; set; \} - - // How many items to refresh (each time the refresh task is invoked) - public long? MaxItemsToProcess \{ get; set; \} -\} -`} - - - -| Parameter | Type | Description | -| - | - | - | -| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | -| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | -| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | - - - -## Configure from Studio - -Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. - -![NoSQL DB Server - Document Refresh](./assets/StudioRefresh.png) - - - - diff --git a/versioned_docs/version-7.1/server/extensions/_expiration-csharp.mdx b/versioned_docs/version-7.1/server/extensions/content/_expiration-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/server/extensions/_expiration-csharp.mdx rename to versioned_docs/version-7.1/server/extensions/content/_expiration-csharp.mdx diff --git a/versioned_docs/version-7.1/server/extensions/content/_refresh-csharp.mdx b/versioned_docs/version-7.1/server/extensions/content/_refresh-csharp.mdx new file mode 100644 index 0000000000..da7c67738d --- /dev/null +++ b/versioned_docs/version-7.1/server/extensions/content/_refresh-csharp.mdx @@ -0,0 +1,138 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* The Refresh feature increments a document's [change vector](../../server/clustering/replication/change-vector.mdx), + triggering its re-indexation as well as other features that react to document updates. + +* Refresh is scheduled using the `@refresh` flag in a document's [metadata](../../client-api/session/how-to/get-and-modify-entity-metadata.mdx). + +* In this page: + * [Overview](../../server/extensions/refresh.mdx#overview) + * [Examples](../../server/extensions/refresh.mdx#examples) + * [Syntax](../../server/extensions/refresh.mdx#syntax) + * [Configure from Studio](../../server/extensions/refresh.mdx#configure-from-studio) + + + +## Overview + +* To set a document refresh time, add the document's `@metadata` a + `@refresh` property with the designated refresh time as a value. + Set the time in **UTC** format, not local time, e.g. - + **"@refresh": "2025-04-22T08:00:00.0000000Z"** + + Metadata properties starting with `@` are for internal RavenDB usage only. + Do _not_ use the metadata `@refresh` property for any other purpose than + scheduling a document's refresh time for the built-in refresh feature. + + +* This will cause the document to refresh **only once**. + When the refresh operation takes place, it will also remove the `@refresh` property from the document. + + + 1. The refresh time value set for the `@refresh` property. + 2. The way you set the [Refresh Configuration](../../server/extensions/refresh.mdx#syntax), + including - + - The interval by which the server refreshes documents (set by default to 60 seconds). + - The way you set **maximal items to process**, potentially limiting the number + of documents that RavenDB is allowed to delete each time the refresh feature is invoked. + + + +* Refreshing a document causes its [change vector](../../server/clustering/replication/change-vector.mdx) + to increment the same way it would after any other kind of update to the document. + This triggers any features that react to document updating, including but not limited to: + - Re-indexing of the document by indexes that cover it + - [Replication](../../server/ongoing-tasks/external-replication.mdx), + [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx), + and [ETL](../../server/ongoing-tasks/etl/basics.mdx) triggering + - Creation of a [document revision](../../document-extensions/revisions/overview.mdx) + + + +## Examples + +#### Example I + +How to set refresh configuration for a database: + + + +{`var refreshConfig = new RefreshConfiguration \{ + Disabled = false, + RefreshFrequencyInSec = 300, + MaxItemsToProcess = 1000 +\}; + +var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig)); +`} + + + +This activates document refreshing and sets the interval at 5 minutes. + + +#### Example II + +How to set a document to refresh 1 hour from now: + + + +{`using (var session = documentStore.OpenSession()) +\{ + var document = session.Load("users/1-A"); + + session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1); + + session.SaveChanges(); +\} +`} + + + + + +## Syntax + +To activate and/or configure document refreshing, send the server a +`RefreshConfiguration` object using the `ConfigureRefreshOperation` operation. +#### `RefreshConfiguration` + + + +{`public class RefreshConfiguration +\{ + // Set 'Disabled' to false to enable the refresh feature + public bool Disabled \{ get; set; \} + + // How frequently to process documents with a @refresh flag + public long? RefreshFrequencyInSec \{ get; set; \} + + // How many items to refresh (each time the refresh task is invoked) + public long? MaxItemsToProcess \{ get; set; \} +\} +`} + + + +| Parameter | Type | Description | +| - | - | - | +| **Disabled** | `bool` | If `true`, refreshing documents is disabled for the entire database.<BR>Default: `true` | +| **RefreshFrequencyInSec** | `long?` | Determines how often (in seconds) the server processes documents that need to be refreshed.<BR>Default: `60` | +| **MaxItemsToProcess** | `long?` | Determines the maximal number of documents the feature is allowed to refresh in one run. | + + + +## Configure from Studio + +Alternatively, document refreshing can also be configured via Studio, under **Settings > Document Refresh**. + +![NoSQL DB Server - Document Refresh](../assets/StudioRefresh.png) + + + + diff --git a/versioned_docs/version-7.1/server/extensions/expiration.mdx b/versioned_docs/version-7.1/server/extensions/expiration.mdx index 81180dfe2c..3c84777ab1 100644 --- a/versioned_docs/version-7.1/server/extensions/expiration.mdx +++ b/versioned_docs/version-7.1/server/extensions/expiration.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExpirationCsharp from './_expiration-csharp.mdx'; +import ExpirationCsharp from './content/_expiration-csharp.mdx'; diff --git a/versioned_docs/version-7.1/server/extensions/refresh.mdx b/versioned_docs/version-7.1/server/extensions/refresh.mdx index 9dc2ef60b8..2cd56d007a 100644 --- a/versioned_docs/version-7.1/server/extensions/refresh.mdx +++ b/versioned_docs/version-7.1/server/extensions/refresh.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import RefreshCsharp from './_refresh-csharp.mdx'; +import RefreshCsharp from './content/_refresh-csharp.mdx'; diff --git a/versioned_docs/version-7.1/server/kb/_document-identifier-generation-csharp.mdx b/versioned_docs/version-7.1/server/kb/content/_document-identifier-generation-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/server/kb/_document-identifier-generation-csharp.mdx rename to versioned_docs/version-7.1/server/kb/content/_document-identifier-generation-csharp.mdx diff --git a/versioned_docs/version-7.1/server/kb/document-identifier-generation.mdx b/versioned_docs/version-7.1/server/kb/document-identifier-generation.mdx index 6bec153835..46a987ed21 100644 --- a/versioned_docs/version-7.1/server/kb/document-identifier-generation.mdx +++ b/versioned_docs/version-7.1/server/kb/document-identifier-generation.mdx @@ -8,7 +8,7 @@ supported_languages: ["csharp"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; +import DocumentIDsCsharp from './content/_document-identifier-generation-csharp.mdx'; diff --git a/versioned_docs/version-7.1/server/storage/_documents-compression-csharp.mdx b/versioned_docs/version-7.1/server/storage/content/_documents-compression-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/server/storage/_documents-compression-csharp.mdx rename to versioned_docs/version-7.1/server/storage/content/_documents-compression-csharp.mdx diff --git a/versioned_docs/version-7.1/server/storage/_documents-compression-nodejs.mdx b/versioned_docs/version-7.1/server/storage/content/_documents-compression-nodejs.mdx similarity index 100% rename from versioned_docs/version-7.1/server/storage/_documents-compression-nodejs.mdx rename to versioned_docs/version-7.1/server/storage/content/_documents-compression-nodejs.mdx diff --git a/versioned_docs/version-7.1/server/storage/documents-compression.mdx b/versioned_docs/version-7.1/server/storage/documents-compression.mdx index 15e82f266b..32619cd17d 100644 --- a/versioned_docs/version-7.1/server/storage/documents-compression.mdx +++ b/versioned_docs/version-7.1/server/storage/documents-compression.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import DocumentsCompressionCsharp from './_documents-compression-csharp.mdx'; -import DocumentsCompressionNodejs from './_documents-compression-nodejs.mdx'; +import DocumentsCompressionCsharp from './content/_documents-compression-csharp.mdx'; +import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/start/_test-driver-csharp.mdx b/versioned_docs/version-7.1/start/content/_test-driver-csharp.mdx similarity index 100% rename from versioned_docs/version-7.1/start/_test-driver-csharp.mdx rename to versioned_docs/version-7.1/start/content/_test-driver-csharp.mdx diff --git a/versioned_docs/version-7.1/start/_test-driver-java.mdx b/versioned_docs/version-7.1/start/content/_test-driver-java.mdx similarity index 100% rename from versioned_docs/version-7.1/start/_test-driver-java.mdx rename to versioned_docs/version-7.1/start/content/_test-driver-java.mdx diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-csharp.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-csharp.mdx deleted file mode 100644 index bf7cae21dc..0000000000 --- a/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-csharp.mdx +++ /dev/null @@ -1,476 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. - We assume you are familiar with .NET development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [.NET 6.x][ms-download-dotnet] - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) -which is set up with dependency injection and X.509 certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project -which provides the .NET client SDK. - -Using the .NET CLI: - - - -{`dotnet add package RavenDB.Client -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with -the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. - - - -{`using Raven.Client.Documents; - -var documentStore = new DocumentStore() \{ - Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, - DatabaseName = "demo", - // Other options -\}; -documentStore.Initialize(); -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - -### Set up dependency injection - -For Azure Function methods, it's recommended to configure the document store and document -sessions with .NET dependency injection. The easiest way is to use the community Nuget package -[RavenDB.DependencyInjection][nuget-ravendb-di]: - - - -{`dotnet add package RavenDB.DependencyInjection -`} - - - -The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure -Functions differs depending on whether your C# functions are running: - -- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions -- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions - -Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` -which exposes two extension methods: - -- `IServiceCollection.AddRavenDbDocStore` -- `IServiceCollection.AddRavenDbAsyncSession` - -The resulting service configuration will look like this: - - - -{`// Requires a using statement -using Raven.DependencyInjection; - -// Configure injection for IDocumentStore -services.AddRavenDbDocStore(); - -// Configure injection for IAsyncDocumentSession -services.AddRavenDbAsyncSession(); -`} - - - -You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: - - - -{`services.AddRavenDbDocStore(options => \{ - // ... - // Customize \`options\` - // ... - - options.Conventions.UseOptimisticConcurrency = true; -\}); -`} - - - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET -applications but Azure Function apps require some manual setup. To support Azure app settings, you will -also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. - -Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. - -Here's an example startup file for an in-process C# Azure Function app: - - - -{`using System; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - builder.Services.AddRavenDbDocStore(); - builder.Services.AddRavenDbAsyncSession(); - \} - - public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) - \{ - FunctionsHostBuilderContext context = builder.GetContext(); - - builder.ConfigurationBuilder - // Add support for appsettings.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) - // Add support for appsettings.ENV.json - .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) - // Allow environment variables to override - .AddEnvironmentVariables(); - \} -\} -`} - - - -For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. - -### Using JSON settings - -An example `appsettings.json` file may look like this: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo" - \} -\} -`} - - - -### Using environment variables - -Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). - -You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK -supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from Certificate Store by thumbprint -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.company.ravendb.cloud"], - "DatabaseName": "demo", - "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" - \} -\} -`} - - - -The dependency injection logic will automatically load the certificate from this path without extra code. - -If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: - - - -{`dotnet user-secrets init -dotnet user-secrets set "RavenSettings:CertPassword" "" -`} - - - -However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every -developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes -it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from Certificate Store by Thumbprint - -For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload -a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. - -On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding -it to your Current User store (`CurrentUser\My`): - -![Windows certificate import wizard](./assets/dotnet-certificate-install.jpg) - -The certificate thumbprint is displayed in the details when viewing the certificate information: - -![Windows certificate thumbprint](./assets/dotnet-certificate-thumbprint.jpg) - -You can also install and view certificates using PowerShell through the -[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. - -To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - -Update your `DocumentStore` initialization to load the certificate by its thumbprint using the -`IConfiguration.GetSection` method to retrieve it when building options. -The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. -In Azure, certificates will be stored in the `CurrentUser\My` cert store. - -Here is how the starter template adds support for loading certificates by thumbprint: - - - -{`using System; -using System.IO; -using System.Security.Cryptography.X509Certificates; -using Microsoft.Azure.Functions.Extensions.DependencyInjection; -using Microsoft.Extensions.Configuration; -using Raven.DependencyInjection; - -[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] - -namespace Company.FunctionApp; - -public class Startup : FunctionsStartup -\{ - public override void Configure(IFunctionsHostBuilder builder) - \{ - var context = builder.GetContext(); - - builder.Services.AddRavenDbDocStore(options => - \{ - var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; - - if (!string.IsNullOrWhiteSpace(certThumbprint)) - \{ - var cert = GetRavendbCertificate(certThumbprint); - - options.Certificate = cert; - \} - \}); - - builder.Services.AddRavenDbAsyncSession(); - \} - - private static X509Certificate2 GetRavendbCertificate(string certThumb) - \{ - X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); - certStore.Open(OpenFlags.ReadOnly); - - X509Certificate2Collection certCollection = certStore.Certificates - .Find(X509FindType.FindByThumbprint, certThumb, false); - - // Get the first cert with the thumbprint - if (certCollection.Count > 0) - \{ - X509Certificate2 cert = certCollection[0]; - return cert; - \} - - certStore.Close(); - - throw new Exception($"Certificate \{certThumb\} not found."); - \} -\} -`} - - - -This will only load by thumbprint if it is specified, meaning that you can still load by a physical -`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` -from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` -and `RavenSettings__CertPassword` app settings. - -### Upload Your Client Certificate (.pfx) - -If you are loading a certificate by its thumbprint from the Certificate Store, follow the -steps below to make your uploaded `.pfx` certificate available to your Azure Functions: - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. You can safely delete the password from your device -once the certificate is uploaded in the Portal so as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store -under the `CurrentUser\My` location. -You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for -your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. -This avoids accidentally exposing a certificate to the application that isn't explicitly used. - - - -The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. -To use this method, you will need to use a Windows-based plan. - - - - -## Next Steps - -- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] -- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup -[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection -[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection -[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md -[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate -[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate -[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers -[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store -[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client -[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection - - diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-nodejs.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-nodejs.mdx deleted file mode 100644 index 39a581b8b6..0000000000 --- a/versioned_docs/version-7.1/start/guides/azure-functions/_existing-project-nodejs.mdx +++ /dev/null @@ -1,416 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** is a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - -* Learn more about [how Microsoft Azure Functions work][az-funcs]. - -* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. - We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) - * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) - * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) - * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) - * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) - * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Node.js][nodejs] 18+ - - -For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) -which is set up with PEM certificate support. -You can also reference the template to see how the integration is set up. - - - - -## Installing the RavenDB Client SDK - -Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. - -Using npm: - - - -{`npm install ravendb -`} - - - - - -## Initializing the Document Store - -Import the `DocumentStore` from `ravendb` package to create a new instance with the required -configuration and initialize your connection to RavenDB by calling the `initialize` method. -You can then export a function to initialize a document session to use in your Azure functions. - -Example `db.js` Node module: - - - -{`import \{ DocumentStore \} from "ravendb"; - -const documentStore = new DocumentStore( - ["https://a.free.mycompany.ravendb.cloud"], - "demo", - // authOptions -\}; - -var initialized = false; - -function initialize() \{ - if (initialized) return; - documentStore.initialize(); - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - -For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. - - -In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, -otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. - - -You can set options manually but it's more likely you'll want to configure support for app settings. - - - -## Adding Support for App Settings - -You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. - -Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "https://a.free.company.ravendb.cloud", - "DB_NAME": "demo", - "DB_CERT_PATH": "../certs/company.client.certificate.pfx" - \} -\} -`} - - - -You can then load environment variables through `process.env`: - - - -{`import \{ readFileSync \} from "fs"; -import \{ DocumentStore \} from "ravendb"; - -var documentStore; -var initialized = false; - -function initialize() \{ - if (initialized) return; - - const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync(process.env.DB_CERT_PATH) - \}; - - documentStore = new DocumentStore( - process.env.DB_URLS.split(","), // Split by "," separator - process.env.DB_NAME, - authOptions - \}; - documentStore.initialize(); - - initialized = true; -\} - -export function openAsyncSession() \{ - if (!initialized) \{ - initialize(); - \} - - return documentStore.openAsyncSession(); -\} -`} - - - - - -## Configuring Support for Certificates - -RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. -The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. -There are multiple ways to load a certificate: - -- Load from .pfx files -- Load from PEM-encoded certificate -- Load from Azure Key Vault - -### Load from .pfx Files - -You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: - - - -{`const authOptions = \{ - type: "pfx", - // Read .pfx file using fs.readFileSync - certificate: readFileSync("../cert/company.client.certificate.pfx"), - // Optionally provide the password - password: "" -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - -If the `.pfx` file requires a password, provide it using `password` option. -However, keep in mind that using an absolute physical file path or a password -requires manual steps for every developer working on a project to configure. - - -PFX files can be compromised, especially if they are not password-protected. -Using a physical file also makes it hard to manage and rotate when they expire. -They are only recommended for ease-of-use on your local machine. -For production, it is better to use the Certificate Store method or Azure Key Vault. - - -### Load from PEM-encoded certificate - -For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that -can be provided through Azure app settings without deploying any files. - -Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: - - - -{`-----BEGIN CERTIFICATE----- -MIIFCzCCAvO... ------END CERTIFICATE----- ------BEGIN RSA PRIVATE KEY----- -MIIJKAIBAAK... ------END RSA PRIVATE KEY----- -`} - - - -To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and -set `authOptions` using the `pem` certificate type: - - - -{`const authOptions = \{ - type: "pem", - certificate: process.env.DB_CERT_PEM -\}; - -documentStore = new DocumentStore( - ["https://a.free.company.ravendb.cloud"], - "demo", - authOptions -\}; -documentStore.initialize(); -`} - - - - -Be aware that the Azure portal removes line endings and you will need to manually normalize -the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` -file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. - - -Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: - - - -{`import \{ EOL \} from "os"; -import \{ readFile \} from "fs/promises"; -import \{ DocumentStore \} from "ravendb"; - -let store; -let initialized = false; - -export async function initializeDb(\{ - urls, - databaseName, - dbCertPassword, - dbCertPath, - dbCertPem, - customize, -\}) \{ - if (initialized) return; - - let authOptions = undefined; - - if (dbCertPath) \{ - authOptions = await getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword - ); - \} else if (dbCertPem) \{ - authOptions = getAuthOptionsFromCertPem(dbCertPem); - \} - - store = new DocumentStore(urls, databaseName, authOptions); - - if (customize) \{ - customize(store.conventions); - \} - - store.initialize(); - - initialized = true; - - return store; -\} - -async function getAuthOptionsFromCertificatePath( - dbCertPath, - dbCertPassword -) \{ - return \{ - certificate: await readFile(dbCertPath), - password: dbCertPassword, - type: "pfx", - \}; -\} - -function getAuthOptionsFromCertPem(dbCertPem) \{ - let certificate = dbCertPem; - const isMissingLineEndings = !dbCertPem.includes(EOL); - - if (isMissingLineEndings) \{ - // Typically when pasting values into Azure env vars - certificate = normalizePEM(certificate); - \} - - return \{ - certificate, - type: "pem", - \}; -\} - -function normalizePEM(pem: string): string \{ - return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ - const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); - return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; - \}); -\} - -const PEM_REGEX = - /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; - -export function openDbSession(opts) \{ - if (!initialized) - throw new Error( - "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." - ); - return store.openSession(opts); -\} -`} - - - -This supports using `.pfx` files or a PEM-encoded certificate, if provided. -It normalizes the PEM value if it does not contain line endings. - -### Load from Azure Key Vault - -[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate -encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. - -Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. -However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. - -For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. - - - -## Configuring Azure - -You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. - -### Specifying Path to Certificate - -If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. - -### Specifying PEM Certificate - -If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: - -![.NET update Azure app settings](./assets/js-azure-app-settings.jpg) - -1. Find the `.pem` certificate provided by RavenDB client certificate package -1. Copy its full contents -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file - -These values will override `local.settings.json` once deployed on Azure. - - - -## Next Steps - -- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] -- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code -- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions -- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions - - - -[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting -[deployment-considerations]: ../../../start/guides/azure-functions/deployment -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup -[nodejs]: https://nodejs.org -[npm-ravendb-client]: https://npmjs.com/package/ravendb -[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[docs-creating-document-store]: ../../../client-api/creating-document-store -[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ -[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest -[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest -[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js -[tool-stringify]: https://onlinestringtools.com/json-stringify-string - - diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/_overview-csharp.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/_overview-csharp.mdx deleted file mode 100644 index c168184ca0..0000000000 --- a/versioned_docs/version-7.1/start/guides/azure-functions/_overview-csharp.mdx +++ /dev/null @@ -1,393 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a C# Azure Function using the - [RavenDB Azure Functions C# template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with .NET development techniques and the - basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) - * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [.NET 6.x][download-dotnet] - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize a new Git repository. -The template repository lists each clone method you can copy & paste directly. - -**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** - - - -{`npx degit ravendb/templates/azure-functions/csharp-http my-project -cd my-project -git init -`} - - - -**Using Bash or PowerShell:** - - - -{`git clone https://github.com/ravendb/templates my-project -cd my-project -git filter-branch --subdirectory-filter azure-functions/csharp-http -rm -rf .git # Bash -rm -r -force .git # PowerShell -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, restore .NET dependencies with `dotnet`: - - - -{`dotnet restore -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - - - -{`func start -`} - - - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/dotnet-func-start.jpg) - - - - -## Configuring Local Connection to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update -the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. -The default is: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["http://live-test.ravendb.net"], - "DatabaseName": "Northwind" - \} -\} -`} - - - -If using an authenticated RavenDB URL, you will need a local client certificate installed. -Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. - -### Certificate Path and Password (Windows and Linux) - -To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. - -To specify a PFX password, use the .NET User Secrets tool to add a secret locally: - - - -{`dotnet user-secrets init -dotnet user-secrets set RavenSettings:CertPassword "" -`} - - - -Replace `` with your PFX password. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" - \} -\} -`} - - - -### Certificate Thumbprint (Windows Only) - -You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting -`RavenSettings:CertThumbprint`. - -Example `appsettings.json`: - - - -{`\{ - "RavenSettings": \{ - "Urls": ["https://a.free.mycompany.ravendb.cloud"], - "DatabaseName": "company_db", - "CertThumbprint": "" - \} -\} -`} - - - - - -## Creating Function App Resources in Azure - -At this point, the local Function app is ready to be deployed. Before you can do that, -you need to set up the Function App resources in Azure. - -The template includes an ARM deployment option using the **Deploy to Azure** button. -This will open the Azure Portal and walkthrough creating a default Function App with -the required resources and app settings. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come -back here to finish configuring your database connection. - -### Upload Your Client Certificate (.pfx) - -Once the app is created in the portal, follow these steps to upload the client certificate and make -it accessible to your Function. - -![.NET upload certificate to Azure](./assets/dotnet-azure-upload-cert.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click "Certificates" -1. Click the "Bring Your Own Certificate" tab -1. Click "+ Add Certificate" button -1. Upload the RavenDB client certificate (PFX) file -1. Enter the certificate password -1. Once uploaded, click the certificate to view details -1. Copy the "Thumbprint" for the next step - - -The Azure portal will only use the certificate password once on upload. You will not need the password -in your Functions App, only the public thumbprint. -You can safely delete the password from your device once the certificate is uploaded in the Portal so -as not to risk it being discovered. - - -### Configure Application Settings - -![.NET update Azure app settings](./assets/dotnet-azure-app-settings.jpg) - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-website-load-certificates.jpg) - -1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied - - ![.NET WEBSITE_LOAD_CERTIFICATES example](./assets/dotnet-azure-ravensettings__certthumbprint.jpg) - -1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to -1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to - -These values will override `appsettings.json` once deployed on Azure. - - -`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows -Certificate Store under the `CurrentUser\My` location. You can use the wildcard value -`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. -However, it's recommended to be specific and use comma-separated thumbprints so that only -allowed certificates are made available. This avoids accidentally exposing a certificate -to the application that isn't explicitly used. - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. -There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using -the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![.NET Azure Function welcome connected screen](./assets/dotnet-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function -invocation which you can inject into Function classes. - -### Example: Injecting `IAsyncDocumentSession` - -Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_1(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_1")] -public async Task Run( -[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, -ILogger log) -\{ - // Access \`session\` within the body of the function - - var user = await session.LoadAsync("users/100"); - - return new OkObjectResult(user); -\} -`} - - - -You can also inject an `IDocumentStore` to get a reference to the current store instance. - -### Example: Loading a user - - - -{`private readonly IAsyncDocumentSession session; - -public HttpTrigger_2(IAsyncDocumentSession session) -\{ - this.session = session; -\} - -[FunctionName("HttpTrigger_2")] -public async Task Run( - [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, - ILogger log) -\{ - log.LogInformation("C# HTTP trigger function processed a request."); - - var user = await session.LoadAsync("users/" + id); - - return new OkObjectResult(user); -\} -`} - - - -Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB .NET_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization -[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[tool-degit]: https://npmjs.com/package/degit - - - diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/_overview-nodejs.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/_overview-nodejs.mdx deleted file mode 100644 index e9abea53ff..0000000000 --- a/versioned_docs/version-7.1/start/guides/azure-functions/_overview-nodejs.mdx +++ /dev/null @@ -1,332 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - - -* Microsoft **Azure Functions** are a serverless platform that supports multiple - languages and frameworks that let you deploy workloads that scale without managing - any infrastructure. - Learn more about operating Microsoft Azure Functions [here][az-funcs]. - -* In this guide, you will learn how to deploy a Node.js Azure Function using the - [RavenDB Azure Functions Node.js template][template] that is connected to your - RavenDB database. - - This guide assumes you are familiar with Node.js development techniques - and the basics of Azure Function apps. - - -* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). - -* In this page: - * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) - * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) - * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) - * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) - * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) - * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) - * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) - * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) - - - -## Before We Get Started - -You will need the following before continuing: - -- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate -- [Azure Function Core Tools][az-core-tools] 4.x+ -- [Git](https://git-scm.org) -- [Node.js][nodejs] 18+ - -If you are new to Azure Function local development, see the [Getting started guide][az-funcs] -for how to get up and running with your toolchain of choice. - - - -## Create a Local Azure Function App - -The [RavenDB Azure Function template][template] is a template repository on GitHub which means -you can either create a new repository derived from the template or clone and push it to a new repository. - -This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. - -### Creating a New Repository from the Template - -Depending on your environment, there are several ways to clone the template and initialize -a new Git repository. -The template repository lists each clone method you can copy & paste directly, but the fastest -way is by using [degit][tool-degit]. - - - -{`npx degit ravendb/templates/azure-functions/node-http my-project -cd my-project -git init -`} - - - -### Install Dependencies - -After cloning the repository locally, install the Node.js dependencies with `npm`: - - - -{`npm install -`} - - - -By default, the template is configured to connect to the Live Test instance of RavenDB. -Since this is only for testing purposes, next you will configure the app to connect to your existing -RavenDB database. - -### Starting the Function - -You can start the Azure Function locally using: - -`npm start` - -If you are using Visual Studio Code, you can also debug the function with F5 debugging. - -You will see the welcome screen if the template is set up correctly: - -![.NET template welcome screen](./assets/js-func-start.jpg ".NET template welcome screen") - -Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. - - - -## Connecting to RavenDB - -To configure the local version of your Azure Functions app to connect to RavenDB, -you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. -The default is: - - - -{`\{ - "IsEncrypted": false, - "Values": \{ - "AzureWebJobsStorage": "", - "FUNCTIONS_WORKER_RUNTIME": "node", - "DB_URLS": "", - "DB_NAME": "" - \} -\} -`} - - - -### Configure Local Database Certificate - -RavenDB is secured using client-certificate authentication (or Mutual TLS). - -The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. - -Specify the following app settings: - -- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` -- `DB_PASSWORD`: the password that is protecting your PFX file - - -You are not required to use the password-protected PFX locally. -If you do intend to use the password-protected PFX file, you will -need to set `DB_PASSWORD` as an environment variable in your terminal -session (e.g. `export DB_PASSWORD=abc`) or through your terminal -profile (e.g. `.bashrc`). -Do not store the `.pfx` files to source control. - - - - -## Creating a Function App in Azure -At this point, the local Function app is ready to be deployed. There are multiple ways to create -and deploy Function apps using tools like Visual Studio Code or the portal itself. - -Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here -to finish configuring your database connection. - -### Configuring Application Settings - -1. Go to your Azure Functions dashboard in the Portal -1. Click the Application Settings menu -1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to -1. Add an app setting for `DB_NAME` with the database name to connect to - -![JS update Azure app settings](./assets/js-azure-app-settings.jpg) - -These values will override `local.settings.json` once deployed on Azure. - -### Configuring PEM Certificate in Azure - -Azure Functions supports client certificates on both the Consumption or App Service Plans. - -Specify the `DB_CERT_PEM` app settings: - -![JS add DB_CERT_PEM Azure app setting](./assets/js-azure-db-cert-pem.jpg) - -The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. - -You can safely copy/paste the contents of the file into the environment variable in the Azure Portal -without preserving newlines. If you are setting the value in the `local.settings.json` file, you will -need to format the value for JSON using [a stringify tool][tool-stringify]. - - - -Azure allows you to upload PFX certificates to the portal and load them using the -`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use -for Node.js functions. That method is better suited for .NET or Java functions. -**Regardless, this is not yet supported on Linux Consumption-based plans.** For -a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. - -The template is configured to use the PEM certificate method for ease of use across plan types and platforms. - - - - - -## Deploying to Azure - -Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main -ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. - -The template has already been set up to use continuous deployment using GitHub Actions. -For the other methods, see [Deploying Azure Function apps][az-deploy]. - -### Configure GitHub Secrets - -The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -in your repository secrets. - -1. Go to your Azure Functions dashboard in the Azure Portal -1. Click "Get Publish Profile" - - ![download Azure publish profile](./assets/azure-download-publish-profile.jpg) - -1. Download the publish profile -1. Open it and copy the full XML -1. Go to your [GitHub repository's secrets settings][gh-secrets] - - ![add GitHub secret for publish profile](./assets/github-publish-profile-secret.jpg) - -1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` -1. Paste in the value of the publish profile - -### Trigger a Deployment - -Your repository and GitHub action is now set up. To test the deployment, you can push -a commit to the repository. - -If you have already committed and pushed, it is likely that the Action failed and you -can re-run the job using the new secret variable. - - - -## Verify the Connection Works - -If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. - -Once you open the URL in the browser, you should see a welcome screen like this with the connection information: - -![JS Azure func welcome screen](./assets/js-azure-func-success.jpg) - -This means your Azure Functions app is correctly configured and ready to work with RavenDB. - - - -## Using RavenDB in the Azure Functions App - -The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide -a `middleware` helper function that can wrap Azure function handlers. The template includes a database -middleware that opens a new session per request and ensures the document store is initialized once. - -### Exporting an Azure Function trigger with middleware - -By default, Azure Function handlers are exported like `export default httpTrigger;`. - -You will need to change this to export with the `middleware` helper function for any new triggers -being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: - -`export default middleware(httpTrigger, [createDbMiddleware]);` - -### Example: Passing the database middleware to an Azure function handler - - - -{`import \{ Context, HttpRequest \} from "@azure/functions"; - -// Import the middleware helpers -import \{ middleware \} from "@senacor/azure-function-middleware"; -import \{ createDbMiddleware \} from "../db/middleware"; - -const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - context.res = \{ - // status: 200, /* Defaults to 200 */ - body: 'success' - \}; -\}; - -// Export default trigger wrapped with middleware -export default middleware(httpTrigger, [createDbMiddleware]); -`} - - - -The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. - -### Example: Loading a user - - - -{`const httpTrigger = async function ( - context: Context, - req: HttpRequest -): Promise \{ - context.log("HTTP trigger function processed a request."); - - const user = await context.db.load("users/" + req.params.id); - - context.res = \{ - body: JSON.stringify(\{ user \}) - \}; -\}; -`} - - - -Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. - - - -## Tutorial Video - -Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: -<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> - - - -[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started -[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local -[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies -[nodejs]: https://nodejs.org -[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http -[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets -[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup -[docs-get-started]: ../../../start/getting-started -[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work -[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware -[tool-stringify]: https://onlinestringtools.com/json-stringify-string -[tool-degit]: https://npmjs.com/package/degit -[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 - - diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-csharp.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-csharp.mdx new file mode 100644 index 0000000000..c4848bdcf2 --- /dev/null +++ b/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-csharp.mdx @@ -0,0 +1,476 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing C# Azure Functions. + We assume you are familiar with .NET development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [.NET 6.x][ms-download-dotnet] + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions .NET template](../../../start/guides/azure-functions/overview.mdx) +which is set up with dependency injection and X.509 certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [RavenDB.Client][nuget-ravendb-client] Nuget package in your solution or project +which provides the .NET client SDK. + +Using the .NET CLI: + + + +{`dotnet add package RavenDB.Client +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `Raven.Client.Documents` namespace to create a new instance with +the required configuration and initialize your connection to RavenDB by calling the `Initialize` method. + + + +{`using Raven.Client.Documents; + +var documentStore = new DocumentStore() \{ + Urls = new [] \{ "https://a.free.mycompany.ravendb.cloud" \}, + DatabaseName = "demo", + // Other options +\}; +documentStore.Initialize(); +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + +### Set up dependency injection + +For Azure Function methods, it's recommended to configure the document store and document +sessions with .NET dependency injection. The easiest way is to use the community Nuget package +[RavenDB.DependencyInjection][nuget-ravendb-di]: + + + +{`dotnet add package RavenDB.DependencyInjection +`} + + + +The pattern to set up dependency injection to inject an `IAsyncDocumentSession` with Azure +Functions differs depending on whether your C# functions are running: + +- Follow the [in-process DI guide][az-func-di-ip] for C# class library functions +- Follow the [out-of-process DI guide][az-func-di-oop] for .NET isolated functions + +Once set up with the appropriate configuration, add a using statement for `Raven.DependencyInjection` +which exposes two extension methods: + +- `IServiceCollection.AddRavenDbDocStore` +- `IServiceCollection.AddRavenDbAsyncSession` + +The resulting service configuration will look like this: + + + +{`// Requires a using statement +using Raven.DependencyInjection; + +// Configure injection for IDocumentStore +services.AddRavenDbDocStore(); + +// Configure injection for IAsyncDocumentSession +services.AddRavenDbAsyncSession(); +`} + + + +You can customize the options before they get passed down to the underlying `DocumentStore` with an overload: + + + +{`services.AddRavenDbDocStore(options => \{ + // ... + // Customize \`options\` + // ... + + options.Conventions.UseOptimisticConcurrency = true; +\}); +`} + + + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +The RavenDB.DependencyInjection package supports reading settings from `appsettings.json` for ASP.NET +applications but Azure Function apps require some manual setup. To support Azure app settings, you will +also need to add support to override those settings through environment variables by using `Microsoft.Extensions.Configuration`. + +Within your `FunctionsStartup` class, override the `ConfigureAppConfiguration` method to customize how the configuration is read. + +Here's an example startup file for an in-process C# Azure Function app: + + + +{`using System; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + builder.Services.AddRavenDbDocStore(); + builder.Services.AddRavenDbAsyncSession(); + \} + + public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder) + \{ + FunctionsHostBuilderContext context = builder.GetContext(); + + builder.ConfigurationBuilder + // Add support for appsettings.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: true, reloadOnChange: false) + // Add support for appsettings.ENV.json + .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.\{context.EnvironmentName\}.json"), optional: true, reloadOnChange: false) + // Allow environment variables to override + .AddEnvironmentVariables(); + \} +\} +`} + + + +For more on the different configuration providers supported, see [Configuration in ASP.NET Core][ms-docs-aspnet-configuration]. + +### Using JSON settings + +An example `appsettings.json` file may look like this: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo" + \} +\} +`} + + + +### Using environment variables + +Environment variables follow the .NET conventions with `__` being the dot-notation separator (e.g. `RavenSettings__DatabaseName`). + +You can pass environment variables in your terminal profile, OS settings, Docker `env`, on the command-line, or within Azure. + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. The .NET Client SDK +supports `X509Certificate2` which is passed to the `DocumentStore.Certificate` option. There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from Certificate Store by thumbprint +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate path using `RavenSettings:CertFilePath`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.company.ravendb.cloud"], + "DatabaseName": "demo", + "CertFilePath": "..\\\\shared\\\\certs\\\\company.client.certificate.pfx" + \} +\} +`} + + + +The dependency injection logic will automatically load the certificate from this path without extra code. + +If the `.pfx` file requires a password, provide it using the .NET secrets tool by setting `RavenSettings:CertPassword`: + + + +{`dotnet user-secrets init +dotnet user-secrets set "RavenSettings:CertPassword" "" +`} + + + +However, keep in mind that using an absolute physical file path or a user secret requires manual steps for every +developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes +it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from Certificate Store by Thumbprint + +For .NET-based Azure Functions, it's recommended to use the Windows Certificate Store since you can upload +a password-protected .pfx file to the Azure Portal and load it programmatically without deploying any files. + +On your local machine, you can import a certificate on Windows by right-clicking the `.pfx` file and adding +it to your Current User store (`CurrentUser\My`): + +![Windows certificate import wizard](../assets/dotnet-certificate-install.jpg) + +The certificate thumbprint is displayed in the details when viewing the certificate information: + +![Windows certificate thumbprint](../assets/dotnet-certificate-thumbprint.jpg) + +You can also install and view certificates using PowerShell through the +[Import-PfxCertificate][ms-powershell-import-pfxcert] and [Get-Certificate][ms-powershell-get-cert] cmdlets. + +To specify the thumbprint you can add a new `RavenSettings:CertThumbprint` setting: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + +Update your `DocumentStore` initialization to load the certificate by its thumbprint using the +`IConfiguration.GetSection` method to retrieve it when building options. +The [X509Store][ms-docs-x509store] can be used to find certificates by thumbprint. +In Azure, certificates will be stored in the `CurrentUser\My` cert store. + +Here is how the starter template adds support for loading certificates by thumbprint: + + + +{`using System; +using System.IO; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Azure.Functions.Extensions.DependencyInjection; +using Microsoft.Extensions.Configuration; +using Raven.DependencyInjection; + +[assembly: FunctionsStartup(typeof(Company.FunctionApp.Startup))] + +namespace Company.FunctionApp; + +public class Startup : FunctionsStartup +\{ + public override void Configure(IFunctionsHostBuilder builder) + \{ + var context = builder.GetContext(); + + builder.Services.AddRavenDbDocStore(options => + \{ + var certThumbprint = context.Configuration.GetSection("RavenSettings:CertThumbprint").Value; + + if (!string.IsNullOrWhiteSpace(certThumbprint)) + \{ + var cert = GetRavendbCertificate(certThumbprint); + + options.Certificate = cert; + \} + \}); + + builder.Services.AddRavenDbAsyncSession(); + \} + + private static X509Certificate2 GetRavendbCertificate(string certThumb) + \{ + X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser); + certStore.Open(OpenFlags.ReadOnly); + + X509Certificate2Collection certCollection = certStore.Certificates + .Find(X509FindType.FindByThumbprint, certThumb, false); + + // Get the first cert with the thumbprint + if (certCollection.Count > 0) + \{ + X509Certificate2 cert = certCollection[0]; + return cert; + \} + + certStore.Close(); + + throw new Exception($"Certificate \{certThumb\} not found."); + \} +\} +`} + + + +This will only load by thumbprint if it is specified, meaning that you can still load by a physical +`.pfx` path locally if you choose. On Azure, follow the steps below to upload a certificate. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [Azure Key Vault configuration provider][ms-az-key-vault-configuration], you can load `RavenSettings` +from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `RavenSettings__CertFilePath` +and `RavenSettings__CertPassword` app settings. + +### Upload Your Client Certificate (.pfx) + +If you are loading a certificate by its thumbprint from the Certificate Store, follow the +steps below to make your uploaded `.pfx` certificate available to your Azure Functions: + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. You can safely delete the password from your device +once the certificate is uploaded in the Portal so as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows Certificate Store +under the `CurrentUser\My` location. +You can use the wildcard value `*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for +your Function App. However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. +This avoids accidentally exposing a certificate to the application that isn't explicitly used. + + + +The `WEBSITE_LOAD_CERTIFICATES` setting is not supported yet for Linux-based consumption plans. +To use this method, you will need to use a Windows-based plan. + + + + +## Next Steps + +- Learn more about [how to use the RavenDB .NET client SDK][docs-dotnet] +- Reference the [.NET Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet_existing&utm_content=cloud_signup +[docs-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-func-di-ip]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection +[az-func-di-oop]: https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide#dependency-injection +[ms-download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-configuration]: https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/dotnet/api/overview/azure/security.keyvault.certificates-readme +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-net/blob/0e2399f030aa365c13fcd06f891a57ee9154fc60/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md +[ms-powershell-get-cert]: https://learn.microsoft.com/en-us/powershell/module/pki/get-certificate +[ms-powershell-import-pfxcert]: https://learn.microsoft.com/en-us/powershell/module/pki/import-certificate +[ms-docs-aspnet-configuration]: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/#configuration-providers +[ms-docs-x509store]: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509store +[nuget-ravendb-client]: https://www.nuget.org/packages/RavenDB.Client +[nuget-ravendb-di]: https://www.nuget.org/packages/RavenDB.DependencyInjection + + diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-nodejs.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-nodejs.mdx new file mode 100644 index 0000000000..c1218873a7 --- /dev/null +++ b/versioned_docs/version-7.1/start/guides/azure-functions/content/_existing-project-nodejs.mdx @@ -0,0 +1,416 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** is a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + +* Learn more about [how Microsoft Azure Functions work][az-funcs]. + +* In this guide, you will learn how to connect to RavenDB from your existing Node.js Azure Functions. + We assume you are familiar with Node.js development techniques and the basics of Azure Function apps. + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/existing-project.mdx#before-we-get-started) + * [Installing the RavenDB Client SDK](../../../start/guides/azure-functions/existing-project.mdx#installing-the-ravendb-client-sdk) + * [Initializing the Document Store](../../../start/guides/azure-functions/existing-project.mdx#initializing-the-document-store) + * [Adding Support for App Settings](../../../start/guides/azure-functions/existing-project.mdx#adding-support-for-app-settings) + * [Configuring Support for Certificates](../../../start/guides/azure-functions/existing-project.mdx#configuring-support-for-certificates) + * [Configuring Azure](../../../start/guides/azure-functions/existing-project.mdx#configuring-azure) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Node.js][nodejs] 18+ + + +For a brand new Azure Functions app, we recommend using the [RavenDB Azure Functions Node.js template](../../../start/guides/azure-functions/overview.mdx) +which is set up with PEM certificate support. +You can also reference the template to see how the integration is set up. + + + + +## Installing the RavenDB Client SDK + +Get started by installing the [ravendb][npm-ravendb-client] npm package in your project which provides the Node.js client SDK. + +Using npm: + + + +{`npm install ravendb +`} + + + + + +## Initializing the Document Store + +Import the `DocumentStore` from `ravendb` package to create a new instance with the required +configuration and initialize your connection to RavenDB by calling the `initialize` method. +You can then export a function to initialize a document session to use in your Azure functions. + +Example `db.js` Node module: + + + +{`import \{ DocumentStore \} from "ravendb"; + +const documentStore = new DocumentStore( + ["https://a.free.mycompany.ravendb.cloud"], + "demo", + // authOptions +\}; + +var initialized = false; + +function initialize() \{ + if (initialized) return; + documentStore.initialize(); + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + +For more on what options are available, see [Creating a Document Store][docs-creating-document-store]. + + +In Azure Functions, the instance will be shared across function invocations if the Function is warmed up, +otherwise it will be constructed each time the function warms up. For more, see [Deployment Considerations][deployment-considerations]. + + +You can set options manually but it's more likely you'll want to configure support for app settings. + + + +## Adding Support for App Settings + +You will need a way to pass options to the `DocumentStore` on your local machine and when deployed to Azure. + +Node.js Azure Functions support a `local.settings.json` file which you can use to add additional settings locally. For example: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "https://a.free.company.ravendb.cloud", + "DB_NAME": "demo", + "DB_CERT_PATH": "../certs/company.client.certificate.pfx" + \} +\} +`} + + + +You can then load environment variables through `process.env`: + + + +{`import \{ readFileSync \} from "fs"; +import \{ DocumentStore \} from "ravendb"; + +var documentStore; +var initialized = false; + +function initialize() \{ + if (initialized) return; + + const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync(process.env.DB_CERT_PATH) + \}; + + documentStore = new DocumentStore( + process.env.DB_URLS.split(","), // Split by "," separator + process.env.DB_NAME, + authOptions + \}; + documentStore.initialize(); + + initialized = true; +\} + +export function openAsyncSession() \{ + if (!initialized) \{ + initialize(); + \} + + return documentStore.openAsyncSession(); +\} +`} + + + + + +## Configuring Support for Certificates + +RavenDB uses client certificate authentication (mutual TLS) to secure your database connection. +The Node.js client SDK supports `.pfx` files or `.pem` files which is passed to the `authOptions.certificate` option. +There are multiple ways to load a certificate: + +- Load from .pfx files +- Load from PEM-encoded certificate +- Load from Azure Key Vault + +### Load from .pfx Files + +You can load PFX files with or without a password by providing the certificate buffer using `authOptions.certificate`: + + + +{`const authOptions = \{ + type: "pfx", + // Read .pfx file using fs.readFileSync + certificate: readFileSync("../cert/company.client.certificate.pfx"), + // Optionally provide the password + password: "" +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + +If the `.pfx` file requires a password, provide it using `password` option. +However, keep in mind that using an absolute physical file path or a password +requires manual steps for every developer working on a project to configure. + + +PFX files can be compromised, especially if they are not password-protected. +Using a physical file also makes it hard to manage and rotate when they expire. +They are only recommended for ease-of-use on your local machine. +For production, it is better to use the Certificate Store method or Azure Key Vault. + + +### Load from PEM-encoded certificate + +For Node.js-based Azure Functions, it's recommended to use a PEM-encoded certificate that +can be provided through Azure app settings without deploying any files. + +Unlike a `.pfx` file, a PEM-encoded certificate is plain-text encoded: + + + +{`-----BEGIN CERTIFICATE----- +MIIFCzCCAvO... +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +MIIJKAIBAAK... +-----END RSA PRIVATE KEY----- +`} + + + +To pass a PEM-encoded certificate, you can read an environment variable like `DB_CERT_PEM` and +set `authOptions` using the `pem` certificate type: + + + +{`const authOptions = \{ + type: "pem", + certificate: process.env.DB_CERT_PEM +\}; + +documentStore = new DocumentStore( + ["https://a.free.company.ravendb.cloud"], + "demo", + authOptions +\}; +documentStore.initialize(); +`} + + + + +Be aware that the Azure portal removes line endings and you will need to manually normalize +the value for PEM parsing to succeed. If you are setting the value in the `local.settings.json` +file, you will need to format the value for JSON using [a stringify tool][tool-stringify]. + + +Here is how the starter template adds support for loading certificates using a `DB_CERT_PEM` environment variable: + + + +{`import \{ EOL \} from "os"; +import \{ readFile \} from "fs/promises"; +import \{ DocumentStore \} from "ravendb"; + +let store; +let initialized = false; + +export async function initializeDb(\{ + urls, + databaseName, + dbCertPassword, + dbCertPath, + dbCertPem, + customize, +\}) \{ + if (initialized) return; + + let authOptions = undefined; + + if (dbCertPath) \{ + authOptions = await getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword + ); + \} else if (dbCertPem) \{ + authOptions = getAuthOptionsFromCertPem(dbCertPem); + \} + + store = new DocumentStore(urls, databaseName, authOptions); + + if (customize) \{ + customize(store.conventions); + \} + + store.initialize(); + + initialized = true; + + return store; +\} + +async function getAuthOptionsFromCertificatePath( + dbCertPath, + dbCertPassword +) \{ + return \{ + certificate: await readFile(dbCertPath), + password: dbCertPassword, + type: "pfx", + \}; +\} + +function getAuthOptionsFromCertPem(dbCertPem) \{ + let certificate = dbCertPem; + const isMissingLineEndings = !dbCertPem.includes(EOL); + + if (isMissingLineEndings) \{ + // Typically when pasting values into Azure env vars + certificate = normalizePEM(certificate); + \} + + return \{ + certificate, + type: "pem", + \}; +\} + +function normalizePEM(pem: string): string \{ + return pem.replace(PEM_REGEX, (match, certSection, certSectionBody) => \{ + const normalizedCertSectionBody = certSectionBody.replace(/\\s/g, EOL); + return \`-----BEGIN $\{certSection\}-----$\{EOL\}$\{normalizedCertSectionBody.trim()\}$\{EOL\}-----END $\{certSection\}-----$\{EOL\}\`; + \}); +\} + +const PEM_REGEX = + /-----BEGIN ([A-Z\\s]+)-----(\\s?[A-Za-z0-9+\\/=\\s]+?\\s?)-----END \\1-----/gm; + +export function openDbSession(opts) \{ + if (!initialized) + throw new Error( + "DocumentStore is not initialized yet. Must \`initializeDb()\` before calling \`openDbSession()\`." + ); + return store.openSession(opts); +\} +`} + + + +This supports using `.pfx` files or a PEM-encoded certificate, if provided. +It normalizes the PEM value if it does not contain line endings. + +### Load from Azure Key Vault + +[Azure Key Vault][ms-az-key-vault] is a paid service that allows you to store, retrieve, and rotate +encrypted secrets including X.509 Certificates. This is recommended for more robust certificate handling. + +Using the [SecretsClient][ms-az-key-vault-secrets-client], you can load secrets from Key Vault. +However, you will need to use the [CertificateClient][ms-az-key-vault-cert-client] to retrieve a certificate from the vault. + +For more, see the [sample code for using CertificateClient][ms-az-key-vault-sample-get]. + + + +## Configuring Azure + +You will need to configure certificate authentication in Azure. Depending on the method you choose above, the steps vary. + +### Specifying Path to Certificate + +If you are deploying a physical `.pfx` file, you can specify the `DB_CERT_PATH` and `DB_PASSWORD` app settings. + +### Specifying PEM Certificate + +If you are loading a PEM-encoded certificate, follow the steps below to make your `.pem` certificate available to your Azure Functions: + +![.NET update Azure app settings](../assets/js-azure-app-settings.jpg) + +1. Find the `.pem` certificate provided by RavenDB client certificate package +1. Copy its full contents +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add the app setting for `DB_CERT_PEM` and paste the contents of your `.pem` file + +These values will override `local.settings.json` once deployed on Azure. + + + +## Next Steps + +- Learn more about [how to use the RavenDB Node.js client SDK][docs-nodejs] +- Reference the [Node.js Azure Function starter template][gh-ravendb-template] to see the code +- [Troubleshoot][troubleshooting] issues with RavenDB and Azure Functions +- [Deployment Considerations][deployment-considerations] for RavenDB and Azure Functions + + + +[troubleshooting]: ../../../start/guides/azure-functions/troubleshooting +[deployment-considerations]: ../../../start/guides/azure-functions/deployment +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs_existing&utm_content=cloud_signup +[nodejs]: https://nodejs.org +[npm-ravendb-client]: https://npmjs.com/package/ravendb +[docs-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[docs-creating-document-store]: ../../../client-api/creating-document-store +[gh-ravendb-template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[ms-az-key-vault]: https://learn.microsoft.com/en-us/azure/key-vault/ +[ms-az-key-vault-secrets-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-secrets-readme?view=azure-node-latest +[ms-az-key-vault-cert-client]: https://learn.microsoft.com/en-us/javascript/api/overview/azure/keyvault-certificates-readme?view=azure-node-latest +[ms-az-key-vault-sample-get]: https://github.com/Azure/azure-sdk-for-js/blob/30c703fa2179831d330201bdb0fff5ac6c0a8b57/sdk/keyvault/keyvault-certificates/samples/v4/javascript/helloWorld.js +[tool-stringify]: https://onlinestringtools.com/json-stringify-string + + diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-csharp.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-csharp.mdx new file mode 100644 index 0000000000..8fe74d2be8 --- /dev/null +++ b/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-csharp.mdx @@ -0,0 +1,393 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a C# Azure Function using the + [RavenDB Azure Functions C# template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with .NET development techniques and the + basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=1vnpfsD3bSE&). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Configuring Local Connection to RavenDB](../../../start/guides/azure-functions/overview.mdx#configuring-local-connection-to-ravendb) + * [Creating Function App Resources in Azure](../../../start/guides/azure-functions/overview.mdx#creating-function-app-resources-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [.NET 6.x][download-dotnet] + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize a new Git repository. +The template repository lists each clone method you can copy & paste directly. + +**Using `npx` and the [degit][tool-degit] tool if you have Node.js installed:** + + + +{`npx degit ravendb/templates/azure-functions/csharp-http my-project +cd my-project +git init +`} + + + +**Using Bash or PowerShell:** + + + +{`git clone https://github.com/ravendb/templates my-project +cd my-project +git filter-branch --subdirectory-filter azure-functions/csharp-http +rm -rf .git # Bash +rm -r -force .git # PowerShell +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, restore .NET dependencies with `dotnet`: + + + +{`dotnet restore +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + + + +{`func start +`} + + + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/dotnet-func-start.jpg) + + + + +## Configuring Local Connection to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, you will need to update +the `appsettings.json` file with the `RavenSettings:Urls` value and `RavenSettings:DatabaseName` value. +The default is: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["http://live-test.ravendb.net"], + "DatabaseName": "Northwind" + \} +\} +`} + + + +If using an authenticated RavenDB URL, you will need a local client certificate installed. +Learn more about configuring client authentication for RavenDB [here][docs-client-certs]. + +### Certificate Path and Password (Windows and Linux) + +To specify the path to a `.pfx` file, specify a relative or absolute file path using `RavenSettings:CertFilePath`. + +To specify a PFX password, use the .NET User Secrets tool to add a secret locally: + + + +{`dotnet user-secrets init +dotnet user-secrets set RavenSettings:CertPassword "" +`} + + + +Replace `` with your PFX password. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertFilePath": "a.free.mycompany.ravendb.cloud.with.password.pfx" + \} +\} +`} + + + +### Certificate Thumbprint (Windows Only) + +You can also specify a certificate to use from the `CurrentUser\My` Windows certificate store by setting +`RavenSettings:CertThumbprint`. + +Example `appsettings.json`: + + + +{`\{ + "RavenSettings": \{ + "Urls": ["https://a.free.mycompany.ravendb.cloud"], + "DatabaseName": "company_db", + "CertThumbprint": "" + \} +\} +`} + + + + + +## Creating Function App Resources in Azure + +At this point, the local Function app is ready to be deployed. Before you can do that, +you need to set up the Function App resources in Azure. + +The template includes an ARM deployment option using the **Deploy to Azure** button. +This will open the Azure Portal and walkthrough creating a default Function App with +the required resources and app settings. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come +back here to finish configuring your database connection. + +### Upload Your Client Certificate (.pfx) + +Once the app is created in the portal, follow these steps to upload the client certificate and make +it accessible to your Function. + +![.NET upload certificate to Azure](../assets/dotnet-azure-upload-cert.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click "Certificates" +1. Click the "Bring Your Own Certificate" tab +1. Click "+ Add Certificate" button +1. Upload the RavenDB client certificate (PFX) file +1. Enter the certificate password +1. Once uploaded, click the certificate to view details +1. Copy the "Thumbprint" for the next step + + +The Azure portal will only use the certificate password once on upload. You will not need the password +in your Functions App, only the public thumbprint. +You can safely delete the password from your device once the certificate is uploaded in the Portal so +as not to risk it being discovered. + + +### Configure Application Settings + +![.NET update Azure app settings](../assets/dotnet-azure-app-settings.jpg) + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Modify or add app setting for `WEBSITE_LOAD_CERTIFICATES` to the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-website-load-certificates.jpg) + +1. Modify or add app setting for `RavenSettings__CertThumbprint` with the certificate thumbprint you copied + + ![.NET WEBSITE_LOAD_CERTIFICATES example](../assets/dotnet-azure-ravensettings__certthumbprint.jpg) + +1. Modify or add app setting for `RavenSettings__Urls` with the comma-separated list of RavenDB node URLs to connect to +1. Modify or add an app setting for `RavenSettings__DatabaseName` with the database name to connect to + +These values will override `appsettings.json` once deployed on Azure. + + +`WEBSITE_LOAD_CERTIFICATES` makes any specified certificates available in the Windows +Certificate Store under the `CurrentUser\My` location. You can use the wildcard value +`*` for `WEBSITE_LOAD_CERTIFICATES` to load ALL uploaded certificates for your Function App. +However, it's recommended to be specific and use comma-separated thumbprints so that only +allowed certificates are made available. This avoids accidentally exposing a certificate +to the application that isn't explicitly used. + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. +There are 3 main ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you can re-run the job using +the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![.NET Azure Function welcome connected screen](../assets/dotnet-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template sets up a singleton `DocumentStore` and dependency injection for the `IAsyncDocumentStore` per function +invocation which you can inject into Function classes. + +### Example: Injecting `IAsyncDocumentSession` + +Pass the `IAsyncDocumentSession` in a function class constructor to make it available to trigger functions: + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_1(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_1")] +public async Task Run( +[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, +ILogger log) +\{ + // Access \`session\` within the body of the function + + var user = await session.LoadAsync("users/100"); + + return new OkObjectResult(user); +\} +`} + + + +You can also inject an `IDocumentStore` to get a reference to the current store instance. + +### Example: Loading a user + + + +{`private readonly IAsyncDocumentSession session; + +public HttpTrigger_2(IAsyncDocumentSession session) +\{ + this.session = session; +\} + +[FunctionName("HttpTrigger_2")] +public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = "\{id:int\}")] int id, + ILogger log) +\{ + log.LogInformation("C# HTTP trigger function processed a request."); + + var user = await session.LoadAsync("users/" + id); + + return new OkObjectResult(user); +\} +`} + + + +Learn more about using the RavenDB .NET client SDK [here][ravendb-dotnet]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB .NET_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/1vnpfsD3bSE?si=X6hyNiwfzEH5wR8w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[download-dotnet]: https://dotnet.microsoft.com/en-us/download/dotnet/6.0 +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/csharp-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_dotnet&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[docs-client-certs]: ../../../client-api/setting-up-authentication-and-authorization +[ravendb-dotnet]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[tool-degit]: https://npmjs.com/package/degit + + + diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-nodejs.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-nodejs.mdx new file mode 100644 index 0000000000..a6bf58b4c8 --- /dev/null +++ b/versioned_docs/version-7.1/start/guides/azure-functions/content/_overview-nodejs.mdx @@ -0,0 +1,332 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + + +* Microsoft **Azure Functions** are a serverless platform that supports multiple + languages and frameworks that let you deploy workloads that scale without managing + any infrastructure. + Learn more about operating Microsoft Azure Functions [here][az-funcs]. + +* In this guide, you will learn how to deploy a Node.js Azure Function using the + [RavenDB Azure Functions Node.js template][template] that is connected to your + RavenDB database. + + This guide assumes you are familiar with Node.js development techniques + and the basics of Azure Function apps. + + +* Watch our tutorial video [below](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + or [on YouTube](https://www.youtube.com/watch?v=TJdJ3TJK-Sg). + +* In this page: + * [Before We Get Started](../../../start/guides/azure-functions/overview.mdx#before-we-get-started) + * [Create a Local Azure Function App](../../../start/guides/azure-functions/overview.mdx#create-a-local-azure-function-app) + * [Connecting to RavenDB](../../../start/guides/azure-functions/overview.mdx#connecting-to-ravendb) + * [Creating a Function App in Azure](../../../start/guides/azure-functions/overview.mdx#creating-a-function-app-in-azure) + * [Deploying to Azure](../../../start/guides/azure-functions/overview.mdx#deploying-to-azure) + * [Verify the Connection Works](../../../start/guides/azure-functions/overview.mdx#verify-the-connection-works) + * [Using RavenDB in the Azure Functions App](../../../start/guides/azure-functions/overview.mdx#using-ravendb-in-the-azure-functions-app) + * [Tutorial Video](../../../start/guides/azure-functions/overview.mdx#tutorial-video) + + + +## Before We Get Started + +You will need the following before continuing: + +- A [RavenDB Cloud][cloud-signup] account or self-hosted client certificate +- [Azure Function Core Tools][az-core-tools] 4.x+ +- [Git](https://git-scm.org) +- [Node.js][nodejs] 18+ + +If you are new to Azure Function local development, see the [Getting started guide][az-funcs] +for how to get up and running with your toolchain of choice. + + + +## Create a Local Azure Function App + +The [RavenDB Azure Function template][template] is a template repository on GitHub which means +you can either create a new repository derived from the template or clone and push it to a new repository. + +This will set up a local Azure Function app that we will deploy to your Azure account at the end of the guide. + +### Creating a New Repository from the Template + +Depending on your environment, there are several ways to clone the template and initialize +a new Git repository. +The template repository lists each clone method you can copy & paste directly, but the fastest +way is by using [degit][tool-degit]. + + + +{`npx degit ravendb/templates/azure-functions/node-http my-project +cd my-project +git init +`} + + + +### Install Dependencies + +After cloning the repository locally, install the Node.js dependencies with `npm`: + + + +{`npm install +`} + + + +By default, the template is configured to connect to the Live Test instance of RavenDB. +Since this is only for testing purposes, next you will configure the app to connect to your existing +RavenDB database. + +### Starting the Function + +You can start the Azure Function locally using: + +`npm start` + +If you are using Visual Studio Code, you can also debug the function with F5 debugging. + +You will see the welcome screen if the template is set up correctly: + +![.NET template welcome screen](../assets/js-func-start.jpg ".NET template welcome screen") + +Since this is only for testing purposes, next you will configure the connection to your existing RavenDB database. + + + +## Connecting to RavenDB + +To configure the local version of your Azure Functions app to connect to RavenDB, +you will need to update the `local.settings.json` file with the `DB_URLS` value and `DB_NAME` value. +The default is: + + + +{`\{ + "IsEncrypted": false, + "Values": \{ + "AzureWebJobsStorage": "", + "FUNCTIONS_WORKER_RUNTIME": "node", + "DB_URLS": "", + "DB_NAME": "" + \} +\} +`} + + + +### Configure Local Database Certificate + +RavenDB is secured using client-certificate authentication (or Mutual TLS). + +The template supports loading certificate through physical `.pfx` files (X.509 certificates) locally. + +Specify the following app settings: + +- `DB_CERT_PATH`: the absolute path or relative path from the project root to your `.pfx` file, e.g. `../certs/db.pfx` +- `DB_PASSWORD`: the password that is protecting your PFX file + + +You are not required to use the password-protected PFX locally. +If you do intend to use the password-protected PFX file, you will +need to set `DB_PASSWORD` as an environment variable in your terminal +session (e.g. `export DB_PASSWORD=abc`) or through your terminal +profile (e.g. `.bashrc`). +Do not store the `.pfx` files to source control. + + + + +## Creating a Function App in Azure +At this point, the local Function app is ready to be deployed. There are multiple ways to create +and deploy Function apps using tools like Visual Studio Code or the portal itself. + +Follow the guide of your choice in the Microsoft docs. Once the app is created, come back here +to finish configuring your database connection. + +### Configuring Application Settings + +1. Go to your Azure Functions dashboard in the Portal +1. Click the Application Settings menu +1. Add an app setting for `DB_URLS` with the comma-separated list of RavenDB node URLs to connect to +1. Add an app setting for `DB_NAME` with the database name to connect to + +![JS update Azure app settings](../assets/js-azure-app-settings.jpg) + +These values will override `local.settings.json` once deployed on Azure. + +### Configuring PEM Certificate in Azure + +Azure Functions supports client certificates on both the Consumption or App Service Plans. + +Specify the `DB_CERT_PEM` app settings: + +![JS add DB_CERT_PEM Azure app setting](../assets/js-azure-db-cert-pem.jpg) + +The value should be the contents of the PEM-encoded certificate (`.pem` file) downloaded from RavenDB. + +You can safely copy/paste the contents of the file into the environment variable in the Azure Portal +without preserving newlines. If you are setting the value in the `local.settings.json` file, you will +need to format the value for JSON using [a stringify tool][tool-stringify]. + + + +Azure allows you to upload PFX certificates to the portal and load them using the +`WEBSITE_LOAD_CERTIFICATES` app setting. However, this is much more difficult to use +for Node.js functions. That method is better suited for .NET or Java functions. +**Regardless, this is not yet supported on Linux Consumption-based plans.** For +a discussion on this, reference [this issue on the Azure Functions repository][ms-issue-linux-certs-unsupported]. + +The template is configured to use the PEM certificate method for ease of use across plan types and platforms. + + + + + +## Deploying to Azure + +Once the Azure app is set up in the portal, you are ready to deploy your app. There are 3 main +ways to deploy your new Azure Function app: GitHub actions, command-line, and an extension. + +The template has already been set up to use continuous deployment using GitHub Actions. +For the other methods, see [Deploying Azure Function apps][az-deploy]. + +### Configure GitHub Secrets + +The GitHub actions rely on having a secret environment variable `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +in your repository secrets. + +1. Go to your Azure Functions dashboard in the Azure Portal +1. Click "Get Publish Profile" + + ![download Azure publish profile](../assets/azure-download-publish-profile.jpg) + +1. Download the publish profile +1. Open it and copy the full XML +1. Go to your [GitHub repository's secrets settings][gh-secrets] + + ![add GitHub secret for publish profile](../assets/github-publish-profile-secret.jpg) + +1. Add a new secret: `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` +1. Paste in the value of the publish profile + +### Trigger a Deployment + +Your repository and GitHub action is now set up. To test the deployment, you can push +a commit to the repository. + +If you have already committed and pushed, it is likely that the Action failed and you +can re-run the job using the new secret variable. + + + +## Verify the Connection Works + +If the deployment succeeds, the `HttpTrigger` endpoint should now be available at your Function URL. + +Once you open the URL in the browser, you should see a welcome screen like this with the connection information: + +![JS Azure func welcome screen](../assets/js-azure-func-success.jpg) + +This means your Azure Functions app is correctly configured and ready to work with RavenDB. + + + +## Using RavenDB in the Azure Functions App + +The template uses the [@senacor/azure-function-middleware][npm-middleware] npm package to provide +a `middleware` helper function that can wrap Azure function handlers. The template includes a database +middleware that opens a new session per request and ensures the document store is initialized once. + +### Exporting an Azure Function trigger with middleware + +By default, Azure Function handlers are exported like `export default httpTrigger;`. + +You will need to change this to export with the `middleware` helper function for any new triggers +being added. Import the `createDbMiddleware` function and pass it as the second parameter to `middleware`, like this: + +`export default middleware(httpTrigger, [createDbMiddleware]);` + +### Example: Passing the database middleware to an Azure function handler + + + +{`import \{ Context, HttpRequest \} from "@azure/functions"; + +// Import the middleware helpers +import \{ middleware \} from "@senacor/azure-function-middleware"; +import \{ createDbMiddleware \} from "../db/middleware"; + +const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + context.res = \{ + // status: 200, /* Defaults to 200 */ + body: 'success' + \}; +\}; + +// Export default trigger wrapped with middleware +export default middleware(httpTrigger, [createDbMiddleware]); +`} + + + +The middleware injects a `db` parameter on the `context` object of type `IDocumentSession`. You can access the document session using `context.db` in the function handler. + +### Example: Loading a user + + + +{`const httpTrigger = async function ( + context: Context, + req: HttpRequest +): Promise \{ + context.log("HTTP trigger function processed a request."); + + const user = await context.db.load("users/" + req.params.id); + + context.res = \{ + body: JSON.stringify(\{ user \}) + \}; +\}; +`} + + + +Learn more about using the RavenDB Node.js client SDK [here][ravendb-nodejs]. + + + +## Tutorial Video + +Watch our _Using Azure Functions with RavenDB Node.js_ tutorial: +<iframe width="560" height="315" src="https://www.youtube.com/embed/TJdJ3TJK-Sg?si=m1cSrn2k7EF6z6bW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> + + + +[az-funcs]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-get-started +[az-core-tools]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local +[az-deploy]: https://learn.microsoft.com/en-us/azure/azure-functions/functions-deployment-technologies +[nodejs]: https://nodejs.org +[template]: https://github.com/ravendb/templates/tree/main/azure-functions/node-http +[gh-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets +[cloud-signup]: https://cloud.ravendb.net?utm_source=ravendb_docs&utm_medium=web&utm_campaign=howto_template_azurefns_nodejs&utm_content=cloud_signup +[docs-get-started]: ../../../start/getting-started +[ravendb-nodejs]: ../../../client-api/session/what-is-a-session-and-how-does-it-work +[npm-middleware]: https://npmjs.com/package/@senacor/azure-function-middleware +[tool-stringify]: https://onlinestringtools.com/json-stringify-string +[tool-degit]: https://npmjs.com/package/degit +[ms-issue-linux-certs-unsupported]: https://github.com/Azure/Azure-Functions/issues/1644 + + diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/existing-project.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/existing-project.mdx index e286007d97..f4fdbd70cd 100644 --- a/versioned_docs/version-7.1/start/guides/azure-functions/existing-project.mdx +++ b/versioned_docs/version-7.1/start/guides/azure-functions/existing-project.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import ExistingProjectCsharp from './_existing-project-csharp.mdx'; -import ExistingProjectNodejs from './_existing-project-nodejs.mdx'; +import ExistingProjectCsharp from './content/_existing-project-csharp.mdx'; +import ExistingProjectNodejs from './content/_existing-project-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/start/guides/azure-functions/overview.mdx b/versioned_docs/version-7.1/start/guides/azure-functions/overview.mdx index a6a64cbfdb..08abe10050 100644 --- a/versioned_docs/version-7.1/start/guides/azure-functions/overview.mdx +++ b/versioned_docs/version-7.1/start/guides/azure-functions/overview.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "nodejs"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import OverviewCsharp from './_overview-csharp.mdx'; -import OverviewNodejs from './_overview-nodejs.mdx'; +import OverviewCsharp from './content/_overview-csharp.mdx'; +import OverviewNodejs from './content/_overview-nodejs.mdx'; diff --git a/versioned_docs/version-7.1/start/test-driver.mdx b/versioned_docs/version-7.1/start/test-driver.mdx index 1bb5c13200..e623cda9a6 100644 --- a/versioned_docs/version-7.1/start/test-driver.mdx +++ b/versioned_docs/version-7.1/start/test-driver.mdx @@ -8,8 +8,8 @@ supported_languages: ["csharp", "java"] import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -import TestDriverCsharp from './_test-driver-csharp.mdx'; -import TestDriverJava from './_test-driver-java.mdx'; +import TestDriverCsharp from './content/_test-driver-csharp.mdx'; +import TestDriverJava from './content/_test-driver-java.mdx';